DocumentationAPI Reference
API ChangelogOpenAPI SpecStatus

Serialization

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 nameValue
dataA full serialization of the affected resource, as defined by the endpoint.
includedFull 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.
metaOther 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

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).

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": "..."
  }
}