Learn how the Persona API structures data using the JSON:API specification. This section explains data serialization, relationships, and how to optimize responses with sparse fieldsets. We'll walk through examples using the Retrieve an Inquiry endpoint.

Data organization overview

Persona’s API follows a consistent, portable data model:

Predictable: Each resource type (e.g., inquiry, account) has a defined shape and attributes.
Implicit Relationships: Connected resources (e.g., inquiries and their verifications) are automatically linked and accessible via relationships.
Portable: API responses are standardized and compatible across environments.

This makes it easier to fetch individual resources, include related data, or streamline responses with filters.

Serialization

Serialization is the process of converting data into a consistent structure and for the Persona API, this is an important concept to help ensure that you can get data that you need and know how to obtain additional or specific pieces of data. Persona uses the JSON:API specification to deliver predictable, machine-readable responses in JSON-encoded bodies.

There are many benefits of this type of serialization including:

Performance: Faster responses with default payloads containing commonly needed data across various use cases.
Privacy: Ability to limit exposure of PII by fetching only what is needed.
Clarity: Ability to return only relevant data to simplify integration with Persona.

📘
Sparse fields and include features
The sparse fields feature allows faster responses by returning only the specific PII data you need, which simplifies your integration.
The include feature lets you easily retrieve additional data by leveraging relationships between resources and objects.

Data structure

Request

The request format depends on the endpoint type. For data retrieve endpoints like GET /inquiries/:id, a request body is not needed. However, when creating or updating with POST or PATCH endpoints, you may need to include specific parameters related to the data object.

Example of a `POST` Request

Let’s look at an example of a POST request. The Create an Inquiry endpoint helps you create an Inquiry with an inquiry-template-id. However you can also create an Account through the endpoint if you provide additional data. For more details about creating an Account with this endpoint here.

curl --request POST \
     --url https://api.withpersona.com/api/v1/inquiries \
     --header 'Persona-Version: 2023-01-05' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {persona-api-key}' \
     --header 'content-type: application/json' \
     --data '
{
  "data": {
    "attributes": {
      "template-id": "tmpl_ABC123",
      "inquiry-template-id": "itmpl_ABC123",
      "inquiry-template-version-id": "itmplv_ABC123",
      "account-id": "act_ABC123",
      "creator-email-address": "[email protected]",
      "theme-id": "the_ABC123",
      "theme-set-id": "theset_ABC123",
      "redirect-uri": "https://yoururl.com/redirect",
      "note": "A note about this inquiry",
      "tags": [
        "string"
      ],
      "initial-step-name": "string"
    }
  },
  "meta": {
    "auto-create-account": true,
    "auto-create-account-type-id": "acttp_ABC123",
    "auto-create-account-reference-id": "my_reference_id",
    "expiration-after-create-interval-seconds": 86400,
    "expiration-after-start-interval-seconds": 86400,
    "expiration-after-resume-interval-seconds": 86400,
    "one-time-link-expiration-seconds": 3600
  }
}

📘
Note: You will need to replace {persona-api-key} with your Persona API Key

Example of a `GET` Request

Here’s an example of using the Retrieve an Inquiry endpoint with a GET request. To get data for a specific Inquiry, you will need both an inquiry-id and a persona-api-key.

curl --request GET \
     --url https://api.withpersona.com/api/v1/inquiries/{inquiry-id} \
     --header 'Persona-Version: 2023-01-05' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {persona-api-key}'

Check the specific API reference documentation for details.

Responses

The response format follows a consistent structure. For data retrieve endpoints like GET /inquiries/:id, responses include a primary resource object. For create or update endpoints using POST or PATCH, responses contain the newly created or modified resource with its updated attributes.

All Persona API responses follow JSON:API specification and has the following components::

data: the primary resource
included: related resources
meta: additional context

`data` key

The data key contains an object representing the serialized data of the primary resource.

Each object contains:

type: The resource type, such as inquiry
id: A globally unique string that identifies the resource
attributes: An object of fields and values for that resource
relationships: References to related resources

The following examples use the Retrieve an Inquiry endpoint to demonstrate response formats. For brevity, some sections are abbreviated with "…": "…".

# GET <https://api.withpersona.com/api/v1/inquiries/inq_ABC123>

{
  "data": {
    "type": "inquiry",
    "id": "inq_ABC123",
    "attributes": {
      "status": "approved",
      "reference-id": "abc-123",
      "note": null,
      "behaviors": {
        "api-version-less-than-minimum-count": null,
        "autofill-cancels": 22,
        "...": "...",
      },
      "tags": [],
      "creator": "[email protected]",
      "reviewer-comment": null,
      "updated-at": "2025-05-05T18:02:57.000Z",
      "...": "...",
      "previous-step-name": "verification_aamva",
      "next-step-name": "aamva_retry",
      "name-first": "Jane",
      "name-middle": "Marie",
      "...": "...",
      "fields": {
        "name-first": {
          "type": "string",
          "value": "Jane"
        },
        "name-middle": {
          "type": "string",
          "value": "Marie"
        },
        "...": {
          "type": "...",
          "value": "..."
        },
      },
    },
    "relationships": {
      "account": {
        "data": {
          "type": "account",
          "id": "act_ABC123"
        }
      },
      "template": {
        "data": null
      },
      "inquiry-template": {
        "data": {
          "type": "inquiry-template",
          "id": "itmpl_ABC123"
        }
      },
      "inquiry-template-version": {
        "data": {
          "type": "inquiry-template-version",
          "id": "itmplv_ABC123"
        }
      },
      "transaction": {
        "data": null
      },
      "reviewer": {
        "data": {
          "type": "workflow-run",
          "id": "wfr_ABC123"
        }
      },
      "reports": {
        "data": []
      },
      "verifications": {
        "data": [
          {
            "type": "verification/aamva",
            "id": "ver_ABC123"
          }
        ]
      },
      "sessions": {
        "data": [
          {
            "type": "inquiry-session",
            "id": "iqse_ABC123"
          },
          {
            "type": "inquiry-session",
            "id": "iqse_ABC123"
          }
        ]
      },
      "documents": {
        "data": []
      },
      "selfies": {
        "data": []
      }
    }
  },
  "included": [
    {
      "type": "verification/aamva",
      "id": "ver_ABC123",
      "attributes": {
        "status": "passed",
        "created-at": "2025-05-05T17:56:14.000Z",
        "created-at-ts": 1746467774,
        "submitted-at": "2025-05-05T17:56:14.000Z",
        "submitted-at-ts": 1746467774,
        "completed-at": "2025-05-05T17:56:14.000Z",
        "completed-at-ts": 1746467774,
        "country-code": null,
        "name-first": "Jane",
        "...": "...",
        "checks": [
          {
            "name": "aamva_address_comparison",
            "status": "passed",
            "reasons": [],
            "requirement": "not_required",
            "metadata": {
              "match-result": null
            }
          },
          {
            "name": "aamva_birthdate_comparison",
            "status": "passed",
            "reasons": [],
            "requirement": "required",
            "metadata": {
              "match-result": null
            }
          },
          {
            "...": "..."
            }
          },
        ],
      },
      "relationships": {
        "inquiry": {
          "data": {
            "type": "inquiry",
            "id": "inq_ABC123"
          }
        },
        "template": {
          "data": null
        },
        "inquiry-template-version": {
          "data": {
            "type": "inquiry-template-version",
            "id": "itmplv_ABC123"
          }
        },
        "inquiry-template": {
          "data": {
            "type": "inquiry-template",
            "id": "itmpl_ABC123"
          }
        },
        "verification-template": {
          "data": {
            "type": "verification-template/aamva",
            "id": "vtmpl_ABC123"
          }
        },
        "verification-template-version": {
          "data": {
            "type": "verification-template-version/aamva",
            "id": "vtmplv_ABC123"
          }
        },
        "transaction": {
          "data": null
        }
      }
    },
    {
      "type": "inquiry-session",
      "id": "iqse_ABC123",
      "attributes": {
        "status": "expired",
        "...": "...",
      },
      "relationships": {
        "inquiry": {
          "data": {
            "type": "inquiry",
            "id": "inq_ABC123"
          }
        },
        "device": {
          "data": {
            "type": "device",
            "id": "dev_ABC123"
          }
        },
        "network": {
          "data": {
            "type": "network",
            "id": "net_ABC123"
          }
        }
      }
    },
    {
      "type": "inquiry-session",
      "id": "iqse_ABC123",
      "attributes": {
        "status": "expired",
        "...": "...",
      },
      "relationships": {
        "inquiry": {
          "data": {
            "type": "inquiry",
            "id": "inq_ABC123"
          }
        },
        "device": {
          "data": {
            "type": "device",
            "id": "dev_ABC123"
          }
        },
        "network": {
          "data": {
            "type": "network",
            "id": "net_ABC123"
          }
        }
      }
    },
    {
      "type": "inquiry-template",
      "id": "itmpl_ABC123",
      "attributes": {
        "status": "active",
        "name": "AAMVA",
        "embedded-flow-domain-allowlist": [],
        "hosted-flow-subdomains": [],
        "hosted-flow-redirect-uri-schemes": []
      },
      "relationships": {
        "latest-published-version": {
          "data": {
            "type": "inquiry-template-version",
            "id": "itmplv_ABC123"
          }
        }
      }
    }
  ]
}

`attributes` key

The attributes key includes all standard fields for a resource, including nested objects such as fields. By default, Persona returns the full attribute set unless you use Sparse Fieldsets.

Within attributes, the fields object contains information defined in the resource’s field schema. In the Persona Dashboard, admins can configure and edit field schemas for certain objects. These schemas define which fields are collected, their labels, accepted formats and if they are required.

When a resource type supports field schemas, the fields object mirrors the structure and keys defined in that schema. These field keys match what you see in the Dashboard’s schema editor, making it easier to correlate API response with your configured data model.

Even resources without editable field schemas (like Verifications or Reports) include a fields object that exposes structured data relevant to that object, though you can’t modify their schema in the Dashboard.

Learn more about field schemas for each object type in their field editor documentation: Inquiries, Accounts, Transactions, Cases.

`relationships` key

The relationships key contains the type and id of related resources. These serve as lightweight pointers to objects listed in the included array, which can be fully returned if requested. Each resource has different default relationships, and these may vary depending on your implementation. The core purpose remains consistent: to serve as lightweight pointers. In relationships, you’ll find the type and id of each object. To see more details, you can either use the ?included parameter in your API response or make additional API calls directly to the resource.

Relationships can be:

One-to-one: The data value is a single object with type and id
One-to-many: The data value is an array of objects

📘
All relationship keys (like verifications or template) are predefined and match what’s returned in the response schema. These relationships are predefined. You cannot add or modify them.

`included` key

The included key contains fully serialized versions of resources related to the primary object. You will see the following:

Fully serialized related resources
Relationships explicitly requested via the include parameter, see the include page for more.
An empty array if no relationships are included

`meta` key

This key contains metadata not tied to the resource model. You’ll commonly see:

Operation-specific info
Information that may be pertinent to debugging
Timestamps

Data Model

Data organization overview

Serialization

📘
Sparse fields and include features

Data structure

Request

Example of a `POST` Request

📘
Note: You will need to replace `{persona-api-key}` with your Persona API Key

Example of a `GET` Request

Responses

`data` key

`attributes` key

`relationships` key

📘

`included` key

`meta` key

Data organization overview

Serialization

📘Sparse fields and include features

Data structure

Request

Example of a POST Request

📘Note: You will need to replace {persona-api-key} with your Persona API Key

Example of a GET Request

Responses

data key

attributes key

relationships key

📘

included key

meta key

📘
Sparse fields and include features

Example of a `POST` Request

📘
Note: You will need to replace `{persona-api-key}` with your Persona API Key

Example of a `GET` Request

`data` key

`attributes` key

`relationships` key

`included` key

`meta` key