Response Body

Each Persona API response body contains a set of resources, and attributes of each resource.

You can specify the exact resources and attributes to return in each response, using the include and fields request parameters.

Terminology

Each Persona API returns a set of resources, and attributes of each resource.

• A resource means an entity, such as an inquiry, inquiry template, account, verification, etc.
• An attribute is a piece of information about a resource. For example, an inquiry has attributes like status, reference-id, created-at, etc.

Response schema

Each API response follows the JSON:API specification. Each response body is a single JSON-encoded object with the following keys:

The included and meta fields are added to the response when relevant.

Default behavior

By default, each API returns all attributes of:

• The primary resource: the entity that is fetched or changed
• Some, none, or all of the primary resource’s related resources

For example, the Retrieve Inquiry API returns an inquiry (the primary resource), and can also return entities like the account, verifications, and inquiry template associated with that inquiry (some of the related resources).

If the default response does not include the data you want—or includes too much—you can use the include and fields request parameters to customize the response. See below for details.

Example responses

View sample responses for each API on its reference page:

See Understanding a Persona API payload for a detailed walkthrough of example responses.

View all related resources

Each primary resource may have related resources that can be included in the response.

The data.relationships object lists all available related resources. By default, this relationships object is returned in every response.

Each relationship can be one-to-one or one-to-many. A one-to-one relationship contains a single object, and a one-to-many relationship contains an array of objects. Each object contains the type and id of the related resource.

For example, here is the relationships object for a fetched inquiry:

1
# GET https://api.withpersona.com/api/v1/inquiries/{inquiry-id}
2
3
{
4
  "data": {
5
    "type": "inquiry",
6
    "id": "inq_XXXXXXXXXXXXX",
7
    "attributes": {
8
      "status": "completed",
9
      "...": "..."
10
    },
11
    "relationships": {
12
      "account": {
13
        "data": {
14
          "type": "account",
15
          "id": "act_XXXXXXXXXXXXX"
16
        }
17
      },
18
      "template": {
19
        "data": null
20
      },
21
      "inquiry-template": {
22
        "data": {
23
          "type": "inquiry-template",
24
          "id": "itmpl_XXXXXXXXXXXXX"
25
        }
26
      },
27
      "inquiry-template-version": {
28
        "data": {
29
          "type": "inquiry-template-version",
30
          "id": "itmplv_XXXXXXXXXXXXX"
31
        }
32
      },
33
      "transaction": {
34
        "data": null
35
      },
36
      "reviewer": {
37
        "data": null
38
      },
39
      "reports": {
40
        "data": []
41
      },
42
      "verifications": {
43
        "data": [
44
          {
45
            "type": "verification/government-id",
46
            "id": "ver_XXXXXXXXXXXXX01"
47
          },
48
          {
49
            "type": "verification/government-id",
50
            "id": "ver_XXXXXXXXXXXXX02"
51
          },
52
          {
53
            "type": "verification/selfie",
54
            "id": "ver_XXXXXXXXXXXXX03"
55
          }
56
        ]
57
      },
58
      "sessions": {
59
        "data": [
60
          {
61
            "type": "inquiry-session",
62
            "id": "iqse_XXXXXXXXXXXXX01"
63
          },
64
          {
65
            "type": "inquiry-session",
66
            "id": "iqse_XXXXXXXXXXXXX02"
67
          }
68
        ]
69
      },
70
      "documents": {
71
        "data": [
72
          {
73
            "type": "document/government-id",
74
            "id": "doc_XXXXXXXXXXXXX01"
75
          },
76
          {
77
            "type": "document/government-id",
78
            "id": "doc_XXXXXXXXXXXXX02"
79
          }
80
        ]
81
      },
82
      "selfies": {
83
        "data": [
84
          {
85
            "type": "selfie/profile-and-center",
86
            "id": "self_XXXXXXXXXXXXX"
87
          }
88
        ]
89
      }
90
    }
91
  }
92
}

Note that:

• This inquiry does not have an associated transaction, reviewer, or reports, so these values are null or empty.
• The account relationship is an example of a one-to-one relationship. It contains a single object.
• The verifications relationship is an example of a one-to-many relationship. The contains an array of objects.

Specify related resources

Use the include query parameter to specify which related resources to return in the included array.

Limitations:

• Only one level of nesting is allowed. I.e. ?include=foo.bar is allowed, but not ?include=foo.bar.baz
• The include parameter cannot be used on “list all” endpoints.

Example requests with include

View the sample request in the each tab:

GET https://api.withpersona.com/api/v1/inquiries/{inquiry-id}?include=verifications

1
{
2
  "data": {
3
    "type": "inquiry",
4
    "id": "inq_XXXXXXXXXXXXX",
5
    "attributes": {
6
      "status": "completed",
7
      "reference-id": "asdf",
8
      "created-at": "2023-07-11T18:46:39.000Z",
9
      "...": "..."
10
    },
11
    "relationships": {
12
      "...": "..."
13
    }
14
  },
15
  "included": [
16
    {
17
      "type": "verification/government-id",
18
      "id": "ver_XXXXXXXXXXXXX01",
19
      "attributes": {
20
        "status": "failed",
21
        "created-at": "2023-07-11T20:09:50.000Z",
22
        "...": "..."
23
      },
24
      "relationships": {
25
        "...": "..."
26
      }
27
    },
28
    {
29
      "type": "verification/government-id",
30
      "id": "ver_XXXXXXXXXXXXX02",
31
      "attributes": {
32
        "status": "failed",
33
        "created-at": "2023-07-11T20:10:15.000Z",
34
        "...": "..."
35
      },
36
      "relationships": {
37
        "...": "..."
38
      }
39
    }
40
  ]
41
}

Specify attributes

Use the fields query parameter to specify which attributes should be returned for a given resource type. This lets you retrieve only the data you need.

Notes:

• TYPE is the resource type, e.g. inquiry, verification/government-id, account.
• Attribute names are any keys found under data.attributes in the API response.

Example requests with fields

View the sample request in each tab:

GET https://api.withpersona.com/api/v1/inquiries/{inquiry-id}?fields[inquiry]=status

1
{
2
  "data": {
3
    "type": "inquiry",
4
    "id": "inq_XXXXXXXXXXXXX",
5
    "attributes": {
6
      "status": "completed"
7
    }
8
  }
9
}

Using fields and include together

You can combine include and fields in the same request, and use fields to control attributes on both primary and related resources.

For example, the following request returns:

• The inquiry with only its status attribute
• All related verifications with only their status and created-at attributes

Parameter:

?include=verifications
&fields[inquiry]=status
&fields[verification]=status

Request:

GET https://api.withpersona.com/api/v1/inquiries/{inquiry-id}?include=verifications&fields[inquiry]=status&fields[verification]=status

Response:

1
{
2
  "data": {
3
    "type": "inquiry",
4
    "id": "inq_XXXXXXXXXXXXX",
5
    "attributes": {
6
      "status": "completed"
7
    }
8
  },
9
  "included": [
10
    {
11
      "type": "verification/government-id",
12
      "id": "ver_XXXXXXXXXXXXX01",
13
      "attributes": {
14
        "status": "failed",
15
        "created-at": "2023-07-11T18:47:46.000Z"
16
      }
17
    },
18
    {
19
      "type": "verification/government-id",
20
      "id": "ver_XXXXXXXXXXXXX02",
21
      "attributes": {
22
        "status": "passed",
23
        "created-at": "2023-07-11T18:48:33.000Z"
24
      }
25
    },
26
    {
27
      "type": "verification/selfie",
28
      "id": "ver_XXXXXXXXXXXXX03",
29
      "attributes": {
30
        "status": "passed",
31
        "created-at": "2023-07-11T18:48:54.000Z"
32
      }
33
    }
34
  ]
35
}

Why limit returned data?

Using include and fields to request only the data you need has multiple benefits:

• Reduced data transfer: By excluding attributes you don’t need, you minimize the amount of data flowing into your system.
• Avoid PII transfer: Some resources, like inquiries, have attributes that contains PII. You can restrict the returned data to avoid fetching PII when you don’t need it.
• Faster responses: When you specify only the fields you need, Persona can retrieve and return data more quickly.