---
title: "Create a Graph Query"
method: POST
path: "/graph-queries"
tags: ["graph"]
---

# Create a Graph Query

`POST /graph-queries`

## Request

- Base URL: `https://api.withpersona.com/api/v1`
- URL: `https://api.withpersona.com/api/v1/graph-queries`
- Auth: HTTP bearer

Create a Graph Query

## Query parameters

- `include` string
- `fields` object

## Request body

- object
  - `data` GraphQueriesPostRequestBodyContentApplicationJsonSchemaData, required
    - `attributes` GraphQueriesPostRequestBodyContentApplicationJsonSchemaDataAttributes, required
      - `graph-query-template-id` string, required
      - `parameter-map` object: Required. JSON key-value pairs of parameter name to value. Schema is defined by your Graph Query Template.
      - `variable-map` object: Deprecated, use parameter-map instead. JSON key-value pairs of variable name to value. Schema is defined by your Graph Query Template.
      - `timeout-in-seconds` integer: Number of seconds from now to timeout the graph query. Must be greater than 0 and less than 60.
  - `meta` GraphQueriesPostRequestBodyContentApplicationJsonSchemaMeta
    - `run-sync` boolean: If true, the query will run synchronously and results will be returned in the response. If false, the query will run asynchronously and you will have to poll for results.

## Response `201`

This endpoint returns a Graph Query object and (optionally) its related objects in `included`.

- GraphCreateAGraphQueryResponse201
  - `data` GraphQuery, required: A Graph Query object
    - `type` 'graph-query'
    - `id` string
    - `attributes` GraphQueryAttributes
      - `status` string: Possible values: - submitted - completed - errored - cancelled - timed_out Do not assume this is a static enumeration; Persona may add new values in the future without a versioned update.
      - `params` object: Dynamic query parameters
      - `created-at` string, date-time
      - `updated-at` string, date-time, nullable
      - `errored-at` string, date-time, nullable
      - `completed-at` string, date-time, nullable
      - `redacted-at` string, date-time, nullable: This will be set to the time when the graph query results were redacted. In this case, nodes will also be an empty array.
    - `relationships` GraphQueryRelationships
      - `accounts` GraphQueryRelationshipsAccounts
        - `data` GraphQueryRelationshipsAccountsDataItems[]
          - `id` string
          - `type` 'account'
  - `included` Account[]: Optional included resources, requested via the `include` query parameter.
    - `id` string
    - `attributes` VerificationIncludedObjectsItemsDiscriminatorMappingAccountAttributes
      - `reference-id` string, nullable
      - `account-type-name` string
      - `created-at` string, date-time
      - `updated-at` string, date-time
      - `redacted-at` string, date-time, nullable
      - `fields` VerificationIncludedObjectsItemsDiscriminatorMappingAccountAttributesFields: JSON key-value pairs of field name to field value. Exact schema depends on the configuration of the Account Type for this Account. Keys in `fields` are **not** key inflected.
        - `name` VerificationIncludedObjectsItemsDiscriminatorMappingAccountAttributesFieldsName
          - `type` string
          - `value` VerificationIncludedObjectsItemsDiscriminatorMappingAccountAttributesFieldsNameValue
            - `first` VerificationIncludedObjectsItemsDiscriminatorMappingAccountAttributesFieldsNameValueFirst
              - …
            - `middle` VerificationIncludedObjectsItemsDiscriminatorMappingAccountAttributesFieldsNameValueMiddle
              - …
            - `last` VerificationIncludedObjectsItemsDiscriminatorMappingAccountAttributesFieldsNameValueLast
              - …
        - `address` VerificationIncludedObjectsItemsDiscriminatorMappingAccountAttributesFieldsAddress
          - `type` string
          - `value` VerificationIncludedObjectsItemsDiscriminatorMappingAccountAttributesFieldsAddressValue
            - `street_1` VerificationIncludedObjectsItemsDiscriminatorMappingAccountAttributesFieldsAddressValueStreet1
              - …
            - `street_2` VerificationIncludedObjectsItemsDiscriminatorMappingAccountAttributesFieldsAddressValueStreet2
              - …
            - `subdivision` VerificationIncludedObjectsItemsDiscriminatorMappingAccountAttributesFieldsAddressValueSubdivision
              - …
            - `city` VerificationIncludedObjectsItemsDiscriminatorMappingAccountAttributesFieldsAddressValueCity
              - …
            - `postal_code` VerificationIncludedObjectsItemsDiscriminatorMappingAccountAttributesFieldsAddressValuePostalCode
              - …
            - `country_code` VerificationIncludedObjectsItemsDiscriminatorMappingAccountAttributesFieldsAddressValueCountryCode
              - …
        - `identification_numbers` VerificationIncludedObjectsItemsDiscriminatorMappingAccountAttributesFieldsIdentificationNumbers
          - `type` string
          - `value` VerificationIncludedObjectsItemsDiscriminatorMappingAccountAttributesFieldsIdentificationNumbersValueItems[]
            - `type` string
            - `value` VerificationIncludedObjectsItemsDiscriminatorMappingAccountAttributesFieldsIdentificationNumbersValueItemsValue
              - …
        - `birthdate` VerificationIncludedObjectsItemsDiscriminatorMappingAccountAttributesFieldsBirthdate
          - `type` string
          - `value` string, nullable
        - `phone_number` VerificationIncludedObjectsItemsDiscriminatorMappingAccountAttributesFieldsPhoneNumber
          - `type` string
          - `value` string, nullable
        - `email_address` VerificationIncludedObjectsItemsDiscriminatorMappingAccountAttributesFieldsEmailAddress
          - `type` string
          - `value` string, nullable
        - `selfie_photo` VerificationIncludedObjectsItemsDiscriminatorMappingAccountAttributesFieldsSelfiePhoto
          - `type` 'file'
          - `value` File
            - `filename` string
            - `url` string
            - `byte-size` integer
      - `tags` string[]
      - `account-status` string
      - `birthdate` string, date, nullable: Birthdate, must be in the format "YYYY-MM-DD".
      - `name-first` string, nullable: Given or first name.
      - `name-middle` string, nullable: Middle name.
      - `name-last` string, nullable: Family or last name.
      - `phone-number` string, nullable: Phone number.
      - `email-address` string, nullable: Email address.
      - `address-street-1` string, nullable: Street name of residence address.
      - `address-street-2` string, nullable: Extension of residence address, usually apartment or suite number.
      - `address-city` string, nullable: City of residence address. Not all international addresses use this attribute.
      - `address-subdivision` string, nullable: State or subdivision of residence address. In the US, this should be the unabbreviated name. Not all international addresses use this attribute.
      - `address-postal-code` string, nullable: ZIP or postal code of residence address. Not all international addresses use this attribute.
      - `country-code` string, nullable: ISO 3166-1 alpha 2 country code.
      - `identification-numbers` object: Keys will be the identification class
      - `social-security-number` string, nullable: Social security number.
    - `relationships` VerificationIncludedObjectsItemsDiscriminatorMappingAccountRelationships
      - `account-type` VerificationIncludedObjectsItemsDiscriminatorMappingAccountRelationshipsAccountType
        - `data` VerificationIncludedObjectsItemsDiscriminatorMappingAccountRelationshipsAccountTypeData
          - `id` string
          - `type` 'account-type'

## Other responses

- `400`: The request was unacceptable, often due to invalid parameters.
- `401`: An invalid API key was provided.
- `403`: The given API key doesn’t have permissions to perform the request or a quota has been exceeded.
- `404`: The requested resource doesn’t exist.
- `409`: The request conflicts with another request, often due to attempting to create a duplicate resource.
- `422`: The request modifies the resource in an unacceptable way, often due to an invalid action or parameter.
- `429`: Your organization’s rate limit has been exceeded. We recommend an exponential backoff on requests.

---

[API](https://skmtc.dev/withpersona/apis/withpersona-7.md) - [All operations](https://skmtc.dev/withpersona/apis/withpersona-7/llms.txt) - [OpenAPI document](https://skmtc.dev/withpersona/apis/withpersona-7/revisions/904c4b28844f?raw)