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 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. If you do not see the desired object in the relationships array for the resource returned by an endpoint, you cannot use include to retrieve it.

Please note that at most one level of dot-separated nesting is allowed in the include parameter. That is, ?include=foo.bar is allowed, but requests with ?include=foo.bar.baz are not, and will result in a 400 response.

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