API Reference
Start typing to search…

include

The included key in Persona's API response follows the JSON:API specification. It provides full representations of related resources in a single request, eliminating the need for multiple follow-up requests. By default, API endpoints may return some, all, or none of these related resources under the included key.

Instead of receiving all related data and searching through a large response, you can use the include parameter to specify exactly what information you need.

This page demonstrates how to request related verification objects using the include parameter with the Retrieve an Inquiry endpoint. The include parameter lets you specify exactly which related resources you want returned in the response.

📘

The include parameter is not supported on "list all" endpoints (e.g., GET /inquiries). If used, the API will return a 400 Bad Request error.

Using include

Let's compare three different requests to understand this better:

  1. GET https://api.withpersona.com/api/v1/inquiries/inq_ABC123: Retrieve an Inquiry
  2. GET https://api.withpersona.com/api/v1/inquiries/inq_ABC123?include=verifications: Retrieve an Inquiry with only its verifications
  3. GET https://api.withpersona.com/api/v1/inquiries/inq_ABC123?include=sessions: Retrieve an Inquiry with only its sessions

In these examples, the default response contains all associated Inquiry data. Using include=verifications limits the included section to only verification-related data, while include=sessions limits it to only session-related data.

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"
          }
        }
      }
    }
  ]
}

# GET https://api.withpersona.com/api/v1/inquiries/inq_ABC123?include=verifications

{
  "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
        }
      }
    }
  ]
}
# GET https://api.withpersona.com/api/v1/inquiries/inq_ABC123?include=sessions

{
  "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": "inquiry-session",
      "id": "iqse_ABC123",
      "attributes": {
        "status": "expired",
        "created-at": "2025-05-05T17:54:47.000Z",
        "...": "...",
      },
      "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",
        "created-at": "2025-05-05T17:54:48.000Z",
        "...": "...",
      },
      "relationships": {
        "inquiry": {
          "data": {
            "type": "inquiry",
            "id": "inq_ABC123"
          }
        },
        "device": {
          "data": {
            "type": "device",
            "id": "dev_ABC123"
          }
        },
        "network": {
          "data": {
            "type": "network",
            "id": "net_ABC123"
          }
        }
      }
    }
  ]
}

How include work with relationships

To use the include parameter successfully, the resource you’re requesting must explicitly define its related resources in the relationship object of the response.

This means:

  • Only relationships that appear under the relationships object can be included
  • If a relationship does not appear in relationships, it can not be included using include

📘

You can think of relationships as a map of which related resources are available. The include parameter tells the API which of those to fully serialize into the included 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.

Nested include relationships

You can include one level of nested relationships using dot notation:

?include=foo.bar     ✅
?include=foo.bar.baz   ❌ (Too deep—returns 400)

Comma-separated values include multiple relationships:

?include=foo,bar

Dot-separated paths allow limited nesting:

?include=foo.bar