Data
Requests and responses follow the JSON:API specification, using JSON-encoded bodies. List, fetch, and action endpoints do not require the request to contain a body. Responses contain a single JSON-encoded object with the following keys:
| Key name | Value |
|---|---|
| data | A full serialization of the affected resource, as defined by the endpoint. |
| included | Full serializations of resources related to the affected resource. The include query parameter can be used to request specific related resources (or none) to be included in this list. |
| meta | Other information not in the affected model's attributes, usually specific to the action being performed. |
Example responses for each API can be found on every API reference page
Related resources
Under data, the relationships key will include information about all resources that are related somehow to the primary resource. For example, an inquiry resource will have a relationship sessions that references all inquiry-session resources associated with the given inquiry. The keys within relationships are the canonical names for that relationship.
Relationships can be one-to-one or one-to-many. The value of the data key for any given relationship will be an array for a one-to-many relationship or a hash for a one-to-one relationship with the primary resource.
relationships will only include the type and id of the related resource. You can think of type and id as a composite key that uniquely references resource objects in another part of the response.
Inclusion of related resources
By default, each API will return fully serialized representations of some/none/all of its related resources under the included key. You can use the include query parameter to override this default behavior and request which relationships you'd like to have returned in included (or none). Note that this parameter is not allowed for "list all" endpoints.
The value of the include parameter is a comma-separated (U+002C COMMA, “,”) list of relationship paths. A relationship path is a dot-separated (U+002E FULL-STOP, “.”) list of relationship names. An empty value indicates that no related resources should be returned (included will still be present in the response and its value an empty array).
Anything that is defined in the relationships array for a resource can be requested with the include parameter.
Take the retrieve an inquiry API as an example:
# GET https://withpersona.com/api/v1/inquiries/inq_2CVZ4HyVg7qaboXz2PUHknAn
{
"data": {
"type": "inquiry",
"id": "inq_2CVZ4HyVg7qaboXz2PUHknAn",
"attributes": {
"status": "approved",
"reference-id": null,
"created-at": "2019-09-09T22:40:56.000Z",
"completed-at": "2019-09-09T22:44:51.000Z",
"expired-at": null,
"...": "..."
},
"relationships": {
"reports": {
"data": []
},
"sessions": {
"data": []
},
"template": {
"data": {
"id": "tmpl_JAZjHuAT738Q63BdgCuEJQre",
"type": "template"
}
},
"verifications": {
"data": [
{
"id": "ver_KnqQRXmxmtquRE65CHTzymhR",
"type": "verification/driver-license"
},
{
"id": "ver_2aguhcwq66zcmqipmrqjxw68",
"type": "verification/selfie"
}
]
}
},
},
"included": [
{
"type": "template",
"id": "tmpl_JAZjHuAT738Q63BdgCuEJQre",
"attributes": {
"name": "Acme #1"
},
},
{
"type": "verification/driver-license",
"id": "ver_KnqQRXmxmtquRE65CHTzymhR",
"attributes": {
"status": "passed",
"front-photo-url": "...",
"created-at": "2019-09-09T22:41:29.000Z",
"completed-at": "2019-09-09T22:41:40.000Z",
"...": "..."
},
},
{
"type": "verification/selfie",
"id": "ver_2aguhcwq66zcmqipmrqjxw68",
"attributes": {
"status": "passed",
"center-photo-url": "...",
"left-photo-url": "...",
"right-photo-url": "...",
"created-at": "2019-09-09T22:42:43.000Z",
"completed-at": "2019-09-09T22:42:46.000Z",
"...": "..."
},
}
],
"meta": {
"session-token": "..."
}
}
# GET https://withpersona.com/api/v1/inquiries/inq_2CVZ4HyVg7qaboXz2PUHknAn?include=verifications
{
"data": {
"type": "inquiry",
"id": "inq_2CVZ4HyVg7qaboXz2PUHknAn",
"attributes": {
"status": "approved",
"reference-id": null,
"created-at": "2019-09-09T22:40:56.000Z",
"completed-at": "2019-09-09T22:44:51.000Z",
"expired-at": null,
"...": "..."
},
"relationships": {
"reports": {
"data": []
},
"sessions": {
"data": []
},
"template": {
"data": {
"id": "tmpl_JAZjHuAT738Q63BdgCuEJQre",
"type": "template"
}
},
"verifications": {
"data": [
{
"id": "ver_KnqQRXmxmtquRE65CHTzymhR",
"type": "verification/driver-license"
},
{
"id": "ver_2aguhcwq66zcmqipmrqjxw68",
"type": "verification/selfie"
}
]
}
},
},
"included": [
{
"type": "verification/driver-license",
"id": "ver_KnqQRXmxmtquRE65CHTzymhR",
"attributes": {
"status": "passed",
"front-photo-url": "...",
"created-at": "2019-09-09T22:41:29.000Z",
"completed-at": "2019-09-09T22:41:40.000Z",
"...": "..."
},
},
{
"type": "verification/selfie",
"id": "ver_2aguhcwq66zcmqipmrqjxw68",
"attributes": {
"status": "passed",
"center-photo-url": "...",
"left-photo-url": "...",
"right-photo-url": "...",
"created-at": "2019-09-09T22:42:43.000Z",
"completed-at": "2019-09-09T22:42:46.000Z",
"...": "..."
},
}
],
"meta": {
"session-token": "..."
}
}
# GET https://withpersona.com/api/v1/inquiries/inq_2CVZ4HyVg7qaboXz2PUHknAn?include=
{
"data": {
"type": "inquiry",
"id": "inq_2CVZ4HyVg7qaboXz2PUHknAn",
"attributes": {
"status": "approved",
"reference-id": null,
"created-at": "2019-09-09T22:40:56.000Z",
"completed-at": "2019-09-09T22:44:51.000Z",
"expired-at": null,
"...": "..."
},
"relationships": {
"reports": {
"data": []
},
"sessions": {
"data": []
},
"template": {
"data": {
"id": "tmpl_JAZjHuAT738Q63BdgCuEJQre",
"type": "template"
}
},
"verifications": {
"data": [
{
"id": "ver_KnqQRXmxmtquRE65CHTzymhR",
"type": "verification/driver-license"
},
{
"id": "ver_2aguhcwq66zcmqipmrqjxw68",
"type": "verification/selfie"
}
]
}
},
},
"included": [],
"meta": {
"session-token": "..."
}
}