Skip to content
API Reference/
/
Search Using Demographic...

Verato Person API (1.0.0)

This OpenAPI 3.0 document serves as an enterprise-level template for REST APIs published on the Developer Experience Portal and documented with Redocly Realm.

Download OpenAPI description
person.openapi.json
person.openapi.yaml
Overview
URL
https://developer.example.com/support
API Support Team
api-support@example.com
License
Example API License
Terms of Service
Languages
Servers
Mock server
https://developer.verato.com/_mock/apis/person.openapi
Sandbox environment for development and testing.
https://sandbox.example.com/{basePath}
Production environment for live integrations.
https://api.example.com/{basePath}

Add an Identity to the link stack

Request

Used to add a new identity to the link stack

Security
bearerAuth
Bodyapplication/jsonrequired

The web service request containing identity data

auditIdstring

Audit ID for tracking

customerIdstringrequired

Customer identifier

auditLogMapobject

Audit log entries

contentobject(PostIdentityWsRequest)required

Request to add a new identity to the LINK database

content.​includeEnrichDataboolean

Flag to include enrich data in the response

Default false
content.​identityobject(Identity)required

API object representing a patient or entity identity

content.​identity.​namesArray of objects(Name)

Array of names for this identity

content.​identity.​addressesArray of objects(Address)

Array of addresses for this identity

content.​identity.​datesOfBirthArray of objects(DateOfBirth)

Array of birth dates for this identity

content.​identity.​ssnsArray of objects(SSN)

Array of social security numbers

content.​identity.​gendersArray of objects(Gender)

Array of gender information

content.​identity.​phoneNumbersArray of objects(Phone)

Array of phone numbers

content.​identity.​emailsArray of objects(Email)

Array of email addresses

content.​identity.​deathDetailsArray of objects(DeathDetails)

Death information if applicable

content.​responseIdentityFormatNamesArray of stringsunique

A set of values that indicates the different formats of the Identity to be sent back in the response. If no values are specified, "DEFAULT" is assumed. Valid values: DEFAULT, GROUP_BY_SOURCE, CUSTOM_VIEW

trackingIdstring

Tracking ID for the request

curl -i -X POST \
  https://developer.verato.com/_mock/apis/person.openapi/v2/postIdentity \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "auditId": "string",
    "customerId": "string",
    "auditLogMap": {
      "property1": "string",
      "property2": "string"
    },
    "content": {
      "includeEnrichData": false,
      "identity": {
        "names": [
          {
            "prefix": "string",
            "firstName": "string",
            "middleName": "string",
            "lastName": "string",
            "suffix": "string",
            "sources": [
              {
                "sourceId": "string",
                "sourceName": "string",
                "displayName": "string",
                "nativeId": "string"
              }
            ],
            "clusterStatus": "ACTIVE"
          }
        ],
        "addresses": [
          {
            "type": "string",
            "line1": "string",
            "line2": "string",
            "city": "string",
            "state": "string",
            "postalCode": "string",
            "country": "string",
            "latitude": 0.1,
            "longitude": 0.1,
            "sources": [
              {
                "sourceId": "string",
                "sourceName": "string",
                "displayName": "string",
                "nativeId": "string"
              }
            ],
            "clusterStatus": "ACTIVE"
          }
        ],
        "datesOfBirth": [
          {
            "dateOfBirth": "2019-08-24",
            "sources": [
              {
                "sourceId": "string",
                "sourceName": "string",
                "displayName": "string",
                "nativeId": "string"
              }
            ],
            "clusterStatus": "ACTIVE"
          }
        ],
        "ssns": [
          {
            "ssn": "string",
            "sources": [
              {
                "sourceId": "string",
                "sourceName": "string",
                "displayName": "string",
                "nativeId": "string"
              }
            ],
            "clusterStatus": "ACTIVE"
          }
        ],
        "genders": [
          {
            "gender": "string",
            "sources": [
              {
                "sourceId": "string",
                "sourceName": "string",
                "displayName": "string",
                "nativeId": "string"
              }
            ],
            "clusterStatus": "ACTIVE"
          }
        ],
        "phoneNumbers": [
          {
            "countryCode": "string",
            "number": "string",
            "extension": "string",
            "type": "string",
            "sources": [
              {
                "sourceId": "string",
                "sourceName": "string",
                "displayName": "string",
                "nativeId": "string"
              }
            ],
            "clusterStatus": "ACTIVE"
          }
        ],
        "emails": [
          {
            "email": "user@example.com",
            "type": "string",
            "sources": [
              {
                "sourceId": "string",
                "sourceName": "string",
                "displayName": "string",
                "nativeId": "string"
              }
            ],
            "clusterStatus": "ACTIVE"
          }
        ],
        "deathDetails": [
          {
            "deathIndicator": true,
            "deathDate": "2019-08-24",
            "sources": [
              {
                "sourceId": "string",
                "sourceName": "string",
                "displayName": "string",
                "nativeId": "string"
              }
            ],
            "clusterStatus": "ACTIVE"
          }
        ]
      },
      "responseIdentityFormatNames": [
        "string"
      ]
    },
    "trackingId": "string"
  }'

Responses

Successfully added identity to the link stack

Bodyapplication/json
auditIdstring

Audit ID

successboolean

Whether the operation was successful

unparsedJsonstring

Unparsed JSON if any

warningsArray of strings

List of warnings

retryableErrorboolean

Whether the error is retryable

messagestring

Response message

contentobject(PostIdentityWsResponse)

Response containing the identity record after post operation

errorsArray of strings

List of errors

trackingIdstring

Tracking ID of the request

Response
application/json
{
  "auditId": "string",
  "success": true,
  "unparsedJson": "string",
  "warnings": [
    "string"
  ],
  "retryableError": true,
  "message": "string",
  "content": {
    "identityGroupedBySource": [ … ],
    "linkIdentity": { … },
    "linkId": "string",
    "identity": { … },
    "domains": [ … ],
    "customizedIdentitiesWithSource": { … },
    "customizedIdentities": { … },
    "vinIds": [ … ],
    "events": [ … ],
    "incomingIdentity": { … },
    "enrichedDetails": {}
  },
  "errors": [
    "string"
  ],
  "trackingId": "string"
}

Search Using Demographic Information

Request

Search link database using provided demographic information, return multiple matches ordered by match score

Security
bearerAuth
Bodyapplication/jsonrequired
auditIdstring

Audit identifier for this request

customerIdstringrequired

Customer ID making the request

auditLogMapobject

Map of audit log entries

contentobject(DemographicsSearchWsRequest)required

Request object for demographics query

content.​includeEnrichDataboolean

Flag to include enrich data in the response, defaults to false

Default false
content.​identityobject(Identity)required

API object representing a patient or entity identity

content.​identity.​namesArray of objects(Name)

Array of names for this identity

content.​identity.​addressesArray of objects(Address)

Array of addresses for this identity

content.​identity.​datesOfBirthArray of objects(DateOfBirth)

Array of birth dates for this identity

content.​identity.​ssnsArray of objects(SSN)

Array of social security numbers

content.​identity.​gendersArray of objects(Gender)

Array of gender information

content.​identity.​phoneNumbersArray of objects(Phone)

Array of phone numbers

content.​identity.​emailsArray of objects(Email)

Array of email addresses

content.​identity.​deathDetailsArray of objects(DeathDetails)

Death information if applicable

content.​matchScoreThresholdnumber(double)

Only identities with match scores equal to or above this value will appear in the response. If not provided, then no filtering based on match score is performed.

content.​maxSearchResultsinteger(int32)[ 1 .. 100000000 ]

The number of results to return at one time. Must be greater than 0. If not provided, the system's maximum number of results will be returned.

content.​responseIdentityFormatNamesArray of stringsunique

A set of values that indicates the different formats of the Identity to be sent back in the response. If no values are specified, "DEFAULT" is assumed.

trackingIdstring

Tracking ID for request correlation

curl -i -X POST \
  https://developer.verato.com/_mock/apis/person.openapi/v2/demographicsSearch \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "auditId": "string",
    "customerId": "string",
    "auditLogMap": {
      "property1": "string",
      "property2": "string"
    },
    "content": {
      "includeEnrichData": false,
      "identity": {
        "names": [
          {
            "prefix": "string",
            "firstName": "string",
            "middleName": "string",
            "lastName": "string",
            "suffix": "string",
            "sources": [
              {
                "sourceId": "string",
                "sourceName": "string",
                "displayName": "string",
                "nativeId": "string"
              }
            ],
            "clusterStatus": "ACTIVE"
          }
        ],
        "addresses": [
          {
            "type": "string",
            "line1": "string",
            "line2": "string",
            "city": "string",
            "state": "string",
            "postalCode": "string",
            "country": "string",
            "latitude": 0.1,
            "longitude": 0.1,
            "sources": [
              {
                "sourceId": "string",
                "sourceName": "string",
                "displayName": "string",
                "nativeId": "string"
              }
            ],
            "clusterStatus": "ACTIVE"
          }
        ],
        "datesOfBirth": [
          {
            "dateOfBirth": "2019-08-24",
            "sources": [
              {
                "sourceId": "string",
                "sourceName": "string",
                "displayName": "string",
                "nativeId": "string"
              }
            ],
            "clusterStatus": "ACTIVE"
          }
        ],
        "ssns": [
          {
            "ssn": "string",
            "sources": [
              {
                "sourceId": "string",
                "sourceName": "string",
                "displayName": "string",
                "nativeId": "string"
              }
            ],
            "clusterStatus": "ACTIVE"
          }
        ],
        "genders": [
          {
            "gender": "string",
            "sources": [
              {
                "sourceId": "string",
                "sourceName": "string",
                "displayName": "string",
                "nativeId": "string"
              }
            ],
            "clusterStatus": "ACTIVE"
          }
        ],
        "phoneNumbers": [
          {
            "countryCode": "string",
            "number": "string",
            "extension": "string",
            "type": "string",
            "sources": [
              {
                "sourceId": "string",
                "sourceName": "string",
                "displayName": "string",
                "nativeId": "string"
              }
            ],
            "clusterStatus": "ACTIVE"
          }
        ],
        "emails": [
          {
            "email": "user@example.com",
            "type": "string",
            "sources": [
              {
                "sourceId": "string",
                "sourceName": "string",
                "displayName": "string",
                "nativeId": "string"
              }
            ],
            "clusterStatus": "ACTIVE"
          }
        ],
        "deathDetails": [
          {
            "deathIndicator": true,
            "deathDate": "2019-08-24",
            "sources": [
              {
                "sourceId": "string",
                "sourceName": "string",
                "displayName": "string",
                "nativeId": "string"
              }
            ],
            "clusterStatus": "ACTIVE"
          }
        ]
      },
      "matchScoreThreshold": 0.1,
      "maxSearchResults": 1,
      "responseIdentityFormatNames": [
        "string"
      ]
    },
    "trackingId": "string"
  }'

Responses

Successfully searched demographics database

Bodyapplication/json
auditIdstring

Audit identifier for this response

successboolean

Whether the request was successful

unparsedJsonstring or null

Unparsed JSON if parsing failed

warningsArray of strings

Warning messages from the service

retryableErrorboolean

Whether the error is retryable

messagestring or null

Status message

contentobject(DemographicsSearchWsResponse)

Response object for demographics query

errorsArray of strings

Error messages if any occurred

trackingIdstring or null

Tracking ID for request correlation

Response
application/json
{
  "auditId": "string",
  "success": true,
  "unparsedJson": "string",
  "warnings": [
    "string"
  ],
  "retryableError": true,
  "message": "string",
  "content": {
    "searchResults": [ … ]
  },
  "errors": [
    "string"
  ],
  "trackingId": "string"
}

Query Using Demographic Information

Request

Search link database using provided demographic information to find matching identities

Security
bearerAuth
Bodyapplication/jsonrequired
auditIdstring

Audit identifier for this request

customerIdstringrequired

Customer ID making the request

auditLogMapobject

Map of audit log entries

contentobject(DemographicsQueryWsRequest)required

Request object for demographics query

content.​includeEnrichDataboolean

Flag to include enrich data in the response, defaults to false

Default false
content.​identityobject(Identity)required

API object representing a patient or entity identity

content.​identity.​namesArray of objects(Name)

Array of names for this identity

content.​identity.​addressesArray of objects(Address)

Array of addresses for this identity

content.​identity.​datesOfBirthArray of objects(DateOfBirth)

Array of birth dates for this identity

content.​identity.​ssnsArray of objects(SSN)

Array of social security numbers

content.​identity.​gendersArray of objects(Gender)

Array of gender information

content.​identity.​phoneNumbersArray of objects(Phone)

Array of phone numbers

content.​identity.​emailsArray of objects(Email)

Array of email addresses

content.​identity.​deathDetailsArray of objects(DeathDetails)

Death information if applicable

content.​responseIdentityFormatNamesArray of stringsunique

A set of values that indicates the different formats of the Identity to be sent back in the response. If no values are specified, "DEFAULT" is assumed.

trackingIdstring

Tracking ID for request correlation

curl -i -X POST \
  https://developer.verato.com/_mock/apis/person.openapi/v2/demographicsQuery \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "auditId": "string",
    "customerId": "string",
    "auditLogMap": {
      "property1": "string",
      "property2": "string"
    },
    "content": {
      "includeEnrichData": false,
      "identity": {
        "names": [
          {
            "prefix": "string",
            "firstName": "string",
            "middleName": "string",
            "lastName": "string",
            "suffix": "string",
            "sources": [
              {
                "sourceId": "string",
                "sourceName": "string",
                "displayName": "string",
                "nativeId": "string"
              }
            ],
            "clusterStatus": "ACTIVE"
          }
        ],
        "addresses": [
          {
            "type": "string",
            "line1": "string",
            "line2": "string",
            "city": "string",
            "state": "string",
            "postalCode": "string",
            "country": "string",
            "latitude": 0.1,
            "longitude": 0.1,
            "sources": [
              {
                "sourceId": "string",
                "sourceName": "string",
                "displayName": "string",
                "nativeId": "string"
              }
            ],
            "clusterStatus": "ACTIVE"
          }
        ],
        "datesOfBirth": [
          {
            "dateOfBirth": "2019-08-24",
            "sources": [
              {
                "sourceId": "string",
                "sourceName": "string",
                "displayName": "string",
                "nativeId": "string"
              }
            ],
            "clusterStatus": "ACTIVE"
          }
        ],
        "ssns": [
          {
            "ssn": "string",
            "sources": [
              {
                "sourceId": "string",
                "sourceName": "string",
                "displayName": "string",
                "nativeId": "string"
              }
            ],
            "clusterStatus": "ACTIVE"
          }
        ],
        "genders": [
          {
            "gender": "string",
            "sources": [
              {
                "sourceId": "string",
                "sourceName": "string",
                "displayName": "string",
                "nativeId": "string"
              }
            ],
            "clusterStatus": "ACTIVE"
          }
        ],
        "phoneNumbers": [
          {
            "countryCode": "string",
            "number": "string",
            "extension": "string",
            "type": "string",
            "sources": [
              {
                "sourceId": "string",
                "sourceName": "string",
                "displayName": "string",
                "nativeId": "string"
              }
            ],
            "clusterStatus": "ACTIVE"
          }
        ],
        "emails": [
          {
            "email": "user@example.com",
            "type": "string",
            "sources": [
              {
                "sourceId": "string",
                "sourceName": "string",
                "displayName": "string",
                "nativeId": "string"
              }
            ],
            "clusterStatus": "ACTIVE"
          }
        ],
        "deathDetails": [
          {
            "deathIndicator": true,
            "deathDate": "2019-08-24",
            "sources": [
              {
                "sourceId": "string",
                "sourceName": "string",
                "displayName": "string",
                "nativeId": "string"
              }
            ],
            "clusterStatus": "ACTIVE"
          }
        ]
      },
      "responseIdentityFormatNames": [
        "string"
      ]
    },
    "trackingId": "string"
  }'

Responses

Successfully queried demographics database

Bodyapplication/json
auditIdstring

Audit identifier for this response

successboolean

Whether the request was successful

unparsedJsonstring or null

Unparsed JSON if parsing failed

warningsArray of strings

Warning messages from the service

retryableErrorboolean

Whether the error is retryable

messagestring or null

Status message

contentobject(DemographicsQueryWsResponse)

Response object for demographics query

errorsArray of strings

Error messages if any occurred

trackingIdstring or null

Tracking ID for request correlation

Response
application/json
{
  "auditId": "string",
  "success": true,
  "unparsedJson": "string",
  "warnings": [
    "string"
  ],
  "retryableError": true,
  "message": "string",
  "content": {
    "identityGroupedBySource": [ … ],
    "linkId": "string",
    "identity": { … },
    "domains": [ … ],
    "customizedIdentitiesWithSource": { … },
    "customizedIdentities": { … },
    "vinIds": [ … ],
    "enrichedDetails": {}
  },
  "errors": [
    "string"
  ],
  "trackingId": "string"
}

Query Using an Id

Request

Search link database for Identity with supplied ID (linkId or external entity ID)

Security
bearerAuth
Bodyapplication/jsonrequired
auditIdobject(AuditID)required

Audit identifier for tracking

auditId.​auditIdstring

Unique audit identifier

Example: "audit-123"
customerIdstringrequired

Customer identifier

Example: "customer-456"
auditLogMapobject

Audit logging metadata

Example: {"action":"query_identity","timestamp":"2025-12-16T10:30:00Z"}
contentobject(IdentityIdQueryWsRequest)required

Request object used to query by LinkId or external entity Id

content.​linkIdstringrequired

The id to query for

Example: "link-789"
content.​includeEnrichDataboolean

Flag to include enrich data in the response, defaults to false

Example: true
content.​addVeratoReferenceToEntityboolean

Flag to include verato reference data with the entity in the response

Example: false
content.​responseIdentityFormatNamesArray of stringsunique

A set of values that indicates the different formats of the Identity to be sent back in the response. If no values are specified, "DEFAULT" is assumed.

Example: ["DEFAULT","GROUP_BY_SOURCE"]
trackingIdstring

Request tracking identifier

Example: "track-101112"
curl -i -X POST \
  https://developer.verato.com/_mock/apis/person.openapi/v2/identityIdQuery \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "auditId": "audit-123",
    "customerId": "customer-456",
    "auditLogMap": {
      "action": "query_identity",
      "timestamp": "2025-12-16T10:30:00Z"
    },
    "content": {
      "linkId": "link-789",
      "includeEnrichData": true,
      "responseIdentityFormatNames": [
        "DEFAULT"
      ]
    },
    "trackingId": "track-101112"
  }'

Responses

Successful identity query response

Bodyapplication/json
auditIdobject(AuditID)required

Audit identifier for tracking

auditId.​auditIdstring

Unique audit identifier

Example: "audit-123"
successbooleanrequired

Indicates if the request was successful

Example: true
messagestring

Response message

Example: "OK"
unparsedJsonstring

Raw unparsed JSON response, if applicable

warningsArray of strings

List of warning messages

Example: ["Partial data returned"]
errorsArray of strings

List of error messages

retryableErrorboolean

Indicates if the error is retryable

Example: false
contentobject(IdentityIdQueryWsResponse)

Response object for query by linkId

trackingIdstring

Request tracking identifier

Example: "track-101112"
Response
application/json
{
  "auditId": "audit-123",
  "success": true,
  "message": "OK",
  "trackingId": "track-101112",
  "content": {
    "linkId": "link-789",
    "requestedLinkId": "link-789",
    "identity": { … },
    "identityGroupedBySource": [ … ]
  }
}