Verato PostIdentity API
The PostIdentity API from Verato — 2 operation(s) for postidentity.
OpenAPI Specification
openapi: 3.0.3
info:
title: Verato Organization AddRelationshipService PostIdentity API
version: 2026.1.2
description: 'The Verato Organization API provides comprehensive identity management capabilities for organizations within the Verato LINK platform. This API enables you to:
- **Ingest and manage organization identities**: Add, update, and delete organization records with rich demographic and contact information.
- **Search and query**: Find organizations using demographic data, native IDs, or link IDs (Verato''s golden identifier).
- **Lifecycle management**: Soft-delete and restore organization records while preserving data history.
- **Merge and link operations**: Consolidate duplicate organizations, manage master data relationships, and maintain data lineage.
- **Relationship management**: Define and query relationships between organizations (parent-child, affiliations, etc.).
- **Notifications**: Track and audit identity changes and events across your organization data.
All operations follow a standard request/response envelope pattern with audit tracking, error handling, and optional response format customization.
'
servers:
- url: https://yourveratodomain.com/org-link-ws/svc
description: Production Organization Link API
- url: https://yourveratodomain.com/org-link-ws/svc
description: Sandbox Organization Link API
security:
- basicAuth: []
tags:
- name: PostIdentity
paths:
/postIdentity:
post:
summary: Add an Identity (postIdentity)
description: Adds a new identity into Verato.
operationId: postIdentity
requestBody:
required: true
description: The web service request.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceRequest_postIdentity'
responses:
'200':
description: Successful POST identity operation.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceResponse_postIdentity'
tags:
- PostIdentity
/v2/postIdentity:
post:
summary: Add an Identity (postIdentity)
description: Adds a new identity into Verato.
operationId: post_v2_postIdentity
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceResponse_v2__postIdentity'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceRequest_v2__postIdentity'
examples:
corePerson:
summary: Core Person
value:
responseIdentityFormatNames:
- DEFAULT
- GROUP_BY_SOURCE
- MOST_RECENTLY_ASSERTED
identity:
sources:
- name: test
id: ja-person-5143
names:
- use: official
prefix: Mr.
first: Jordan
middle: A.
last: Avery
suffix: Jr.
credential: MBA
addresses:
- type: home
line1: 4567 Maplewood Ave
line2: Apt 8B
city: Riverton
district: Northside
state: NY
postalCode: '13579'
country: USA
latitude: 40.7128
longitude: -74.006
validFrom: '2008-06-15'
validTo: '2038-06-15'
datesOfBirth:
- dateOfBirth: '1985-04-12'
ssns:
- ssn: 219-08-3746
genders:
- gender: M
genderIdentities:
- genderIdentity: M
phoneNumbers:
- type: mobile
countryCode: '+1'
areaCode: '212'
number: '5552314'
extension: ''
validTo: '2038-06-15'
validFrom: '2008-06-15'
bestTimeToContact:
- day: sat
startTime: 09:00
endTime: '20:00'
allDay: false
emails:
- type: work
email: jordan.avery@samplemail.com
validFrom: '2008-06-15'
validTo: '2038-06-15'
deathDetails:
- deceased: N
dateOfDeath: null
city: null
county: null
state: null
country: null
externalUniqueIdentifier:
- issuer: Riverton Records
value: RV-42109
status: active
startDate: '2008-06-15'
endDate: '2038-06-15'
alternateIdentifiers:
- description: Passport
type: PPN
value: XG9876543
status: active
issuer: Fictitious Passport Office
issueDate: '2012-09-01'
startDate: '2012-09-01'
endDate: '2022-09-01'
multipleBirthIndicator:
- multipleBirthIndicator: false
multipleBirthInteger: 1
birthPlurality: 1
citizenships:
- citizenship: US
photos:
- url: https://images.placeholder.org/people/jordan-avery.jpg
sexualOrientations:
- sexualOrientation: ST
races:
- race: 2106-3
ethnicities:
- ethnicity: 2186-5
religiousAffiliations:
- religiousAffiliation: '1033'
maritalStatuses:
- maritalStatus: M
communicationLanguages:
- language: en
preferred: true
qualifications:
- type: qualification
qualification: MBA
status: active
issuer: Westbridge University
issueDate: '2010-05-22'
validFrom: '2010-05-22'
validTo: '2030-05-22'
consents:
- name: Data Sharing Consent
type: hcd
status: active
isRequired: true
decision: permit
validFrom: '2019-01-01'
validTo: '2029-01-01'
source: participant
regulatoryBasis: hipaa-restrictions
preferences:
- name: SMS Alerts
type: SMS
channels:
- type: SMSWRIT
isOptedIn: true
lastOptedInDate: '2025-07-01'
frequency: monthly
preferredStartTime: 09:00
preferredEndTime: '21:00'
tags:
- PostIdentity
components:
schemas:
names:
type: object
properties:
use:
$ref: '#/components/schemas/CODE-SET_2'
prefix:
$ref: '#/components/schemas/TEXT_2'
first:
$ref: '#/components/schemas/TEXT_2'
middle:
$ref: '#/components/schemas/TEXT_2'
last:
$ref: '#/components/schemas/TEXT_2'
suffix:
$ref: '#/components/schemas/TEXT_2'
credential:
$ref: '#/components/schemas/TEXT_2'
recentEncounter:
type: object
properties:
status:
$ref: '#/components/schemas/CODE-SET_2'
class:
$ref: '#/components/schemas/CODE-SET_2'
priority:
$ref: '#/components/schemas/CODE-SET_2'
type:
$ref: '#/components/schemas/CODE-SET_2'
serviceType:
$ref: '#/components/schemas/CODE-SET_2'
start:
$ref: '#/components/schemas/DATE_2'
end:
$ref: '#/components/schemas/DATE_2'
reason:
$ref: '#/components/schemas/TEXT_2'
diagnosis:
$ref: '#/components/schemas/TEXT_2'
specialArrangement:
$ref: '#/components/schemas/CODE-SET_2'
specialCourtesy:
$ref: '#/components/schemas/CODE-SET_2'
product:
type: object
properties:
name:
$ref: '#/components/schemas/TEXT'
code:
$ref: '#/components/schemas/TEXT'
type:
$ref: '#/components/schemas/CODE-SET'
category:
$ref: '#/components/schemas/TEXT'
price:
$ref: '#/components/schemas/NUMBER'
status:
$ref: '#/components/schemas/TEXT'
description:
$ref: '#/components/schemas/TEXT'
launchDate:
$ref: '#/components/schemas/DATE'
market:
$ref: '#/components/schemas/TEXT'
lineOfBusiness:
$ref: '#/components/schemas/TEXT'
serviceLines:
type: array
items:
type: object
properties:
serviceLine:
$ref: '#/components/schemas/TEXT'
subServiceLine:
$ref: '#/components/schemas/TEXT'
contactInformation:
type: object
properties:
address:
$ref: '#/components/schemas/addresses'
phoneList:
type: array
items:
$ref: '#/components/schemas/phoneNumbers'
faxList:
type: array
items:
$ref: '#/components/schemas/faxNumbers'
bestTimeToContact:
$ref: '#/components/schemas/bestTimeToContact'
example:
address:
line1: 123 Main St
city: Springfield
state: VA
postalCode: '22150'
phoneList:
- number: '5551234567'
type: WORK
bestTimeToContact:
day: MON
startTime: 09:00
endTime: '17:00'
allDay: false
bestTimeToContact:
day: MON
startTime: 09:00
endTime: '17:00'
allDay: false
naicsClassifications:
type: object
properties:
sector:
$ref: '#/components/schemas/CODE-SET'
subSector:
$ref: '#/components/schemas/CODE-SET'
industryGroup:
$ref: '#/components/schemas/CODE-SET'
industry:
$ref: '#/components/schemas/CODE-SET'
nationalIndustry:
$ref: '#/components/schemas/CODE-SET'
Source_2:
type: object
properties:
date:
type: string
description: The date of the source data in ISO format (yyyy-mm-dd).
name:
type: string
description: The name of the data source. Must be unique across Verato.
id:
type: string
description: The ID of an identity within the given data source.
description: Represents the information tracking an identity to a source that contains the identity
CODE-SET_2:
type: string
description: CODE-SET data type, see documentation for more details
ethnicities:
type: object
properties:
ethnicity:
$ref: '#/components/schemas/CODE-SET_2'
IdentityPerSource:
type: object
description: Identity view with attributes grouped by the single source that provided them.
properties:
source:
$ref: '#/components/schemas/Source'
PostIdentityWsRequest:
type: object
description: Adds a new identity to Verato.
required:
- identity
properties:
identity:
$ref: '#/components/schemas/Identity'
responseIdentityFormatNames:
type: array
description: Names of response identity formats to include. If omitted, DEFAULT is assumed.
items:
type: string
sexualOrientations:
type: object
properties:
sexualOrientation:
$ref: '#/components/schemas/CODE-SET_2'
EmailPerSource:
type: object
properties:
identityCluster:
$ref: '#/components/schemas/Email'
firstAsserted:
type: string
description: The date the source first saw this property value.
lastAssertedMetaData:
$ref: '#/components/schemas/CustomerMetaData'
description: Metadata specified when record data was last asserted
email:
$ref: '#/components/schemas/Email'
description: The Email provided by this source
lastAsserted:
type: string
description: The date the source last saw this property value.
firstAssertedMetaData:
$ref: '#/components/schemas/CustomerMetaData'
description: Metadata specified when record data was first asserted
description: ''
emails:
type: object
properties:
email:
$ref: '#/components/schemas/TEXT'
type:
$ref: '#/components/schemas/CODE-SET'
validFrom:
$ref: '#/components/schemas/DATE'
validTo:
$ref: '#/components/schemas/DATE'
PostIdentityWsResponse_2:
type: object
properties:
identityGroupedBySource:
type: array
items:
$ref: '#/components/schemas/IdentityPerSource_2'
description: An alternative view of the link identity where information is grouped by the source. Present if the Request object contains "GROUP_BY_SOURCE" in its identity view names list.
linkIdentity:
$ref: '#/components/schemas/Identity_2'
description: the link identity as it exists in the link database
linkId:
type: string
enum:
- String
description: LinkId of the returned Identity, if any. Null if no match found
identity:
type: string
enum:
- Identity
description: Found identity, if any. Null if no match found
domains:
type: array
items:
$ref: '#/components/schemas/Domain'
uniqueItems: true
description: Domains of the returned Identity, if any. Null if none
customizedIdentitiesWithSource:
type: object
additionalProperties:
type: string
description: An alternative view of the link identity where information is customized according to the view name along with source information. Present if the Request object contains "CUSTOM_VIEW" in its identity view names list.
customizedIdentities:
type: object
additionalProperties:
$ref: '#/components/schemas/Identity_2'
description: An alternative view of the link identity where information is customized according to the view name. Present if the Request object contains "CUSTOM_VIEW" in its identity view names list.
vinIds:
type: array
items:
type: string
uniqueItems: true
description: The VIN IDs associated with the identity
events:
type: array
items:
type: string
incomingIdentity:
$ref: '#/components/schemas/Identity_2'
description: The identity being posted.
enrichedDetails:
type: string
enum:
- EnrichedDetails
description: Enriched details for an Identity that is augmented from the enrich stack
description: PostIdentity service response
DateOfBirth:
type: object
properties:
sources:
type: array
items:
$ref: '#/components/schemas/Source_2'
description: The source for this cluster
dateOfBirth:
type: string
description: The date of birth
clusterStatus:
type: string
enum:
- ACTIVE
- INACTIVE
description: The current clusterStatus
Address:
type: object
properties:
type:
type: string
line1:
type: string
line2:
type: string
city:
type: string
district:
type: string
state:
type: string
postalCode:
type: string
country:
type: string
latitude:
type: number
longitude:
type: number
validFrom:
type: string
format: date
validTo:
type: string
format: date
verifiedAddress:
$ref: '#/components/schemas/VerifiedAddress'
sources:
type: array
items:
$ref: '#/components/schemas/Source_2'
description: The source for this cluster
verifiedAddressMetaData:
$ref: '#/components/schemas/VerifiedAddressMetaData'
clusterStatus:
type: string
enum:
- ACTIVE
- INACTIVE
description: The current clusterStatus
description: API address model
BOOLEAN:
type: boolean
description: BOOLEAN data type, see documentation for more details.
races:
type: object
properties:
race:
$ref: '#/components/schemas/CODE-SET_2'
preferences:
type: object
properties:
name:
$ref: '#/components/schemas/TEXT_2'
type:
$ref: '#/components/schemas/TEXT_2'
channels:
type: array
items: {}
maritalStatuses:
type: object
properties:
maritalStatus:
$ref: '#/components/schemas/CODE-SET_2'
NamePerSource:
type: object
properties:
identityCluster:
$ref: '#/components/schemas/Name'
firstAsserted:
type: string
description: The date the source first saw this property value.
lastAssertedMetaData:
$ref: '#/components/schemas/CustomerMetaData'
description: Metadata specified when record data was last asserted
name:
$ref: '#/components/schemas/Name'
description: The Name provided by this source
lastAsserted:
type: string
description: The date the source last saw this property value.
firstAssertedMetaData:
$ref: '#/components/schemas/CustomerMetaData'
description: Metadata specified when record data was first asserted
description: ''
DeathDetailsPerSource:
type: object
properties:
identityCluster:
$ref: '#/components/schemas/DeathDetails'
firstAsserted:
type: string
description: The date the source first saw this property value.
lastAssertedMetaData:
$ref: '#/components/schemas/CustomerMetaData'
description: Metadata specified when record data was last asserted
deathDetails:
$ref: '#/components/schemas/DeathDetails'
description: The DeathDetails provided by this source
lastAsserted:
type: string
description: The date the source last saw this property value.
firstAssertedMetaData:
$ref: '#/components/schemas/CustomerMetaData'
description: Metadata specified when record data was first asserted
description: ''
TEXT_2:
type: string
description: TEXT data type, see documentation for more details
addresses_2:
type: object
properties:
type:
$ref: '#/components/schemas/CODE-SET_2'
line1:
$ref: '#/components/schemas/TEXT_2'
line2:
$ref: '#/components/schemas/TEXT_2'
city:
$ref: '#/components/schemas/TEXT_2'
district:
$ref: '#/components/schemas/TEXT_2'
state:
$ref: '#/components/schemas/TEXT_2'
postalCode:
$ref: '#/components/schemas/TEXT_2'
country:
$ref: '#/components/schemas/TEXT_2'
latitude:
$ref: '#/components/schemas/NUMBER_2'
longitude:
$ref: '#/components/schemas/NUMBER_2'
validFrom:
$ref: '#/components/schemas/DATE_2'
validTo:
$ref: '#/components/schemas/DATE_2'
TIME_2:
type: string
description: TIME data type, see documentation for more details
PhoneNumberPerSource:
type: object
properties:
identityCluster:
$ref: '#/components/schemas/Phone'
firstAsserted:
type: string
description: The date the source first saw this property value.
phoneNumber:
$ref: '#/components/schemas/Phone'
description: The Phone Number provided by this source
lastAssertedMetaData:
$ref: '#/components/schemas/CustomerMetaData'
description: Metadata specified when record data was last asserted
lastAsserted:
type: string
description: The date the source last saw this property value.
firstAssertedMetaData:
$ref: '#/components/schemas/CustomerMetaData'
description: Metadata specified when record data was first asserted
description: ''
AddressDetailsPerSource:
type: object
properties:
identityCluster:
$ref: '#/components/schemas/AddressDetails'
firstAsserted:
type: string
description: The date the source first saw this property value.
lastAssertedMetaData:
$ref: '#/components/schemas/CustomerMetaData'
description: Metadata specified when record data was last asserted
addressDetails:
$ref: '#/components/schemas/AddressDetails'
description: The Address provided by this source
lastAsserted:
type: string
description: The date the source last saw this property value.
firstAssertedMetaData:
$ref: '#/components/schemas/CustomerMetaData'
description: Metadata specified when record data was first asserted
description: ''
healthInsuranceCoverage:
type: object
properties:
payerName:
$ref: '#/components/schemas/TEXT_2'
status:
$ref: '#/components/schemas/CODE-SET_2'
insuranceType:
$ref: '#/components/schemas/CODE-SET_2'
planType:
$ref: '#/components/schemas/CODE-SET_2'
subscriberId:
$ref: '#/components/schemas/TEXT_2'
relationship:
$ref: '#/components/schemas/CODE-SET_2'
groupNumber:
$ref: '#/components/schemas/TEXT_2'
idNumber:
$ref: '#/components/schemas/TEXT_2'
sequenceNumber:
$ref: '#/components/schemas/TEXT_2'
effectiveDate:
$ref: '#/components/schemas/TEXT_2'
endDate:
$ref: '#/components/schemas/DATE_2'
types:
type: object
properties:
type:
$ref: '#/components/schemas/TEXT'
subType:
$ref: '#/components/schemas/TEXT'
sicClassifications:
type: object
properties:
code:
$ref: '#/components/schemas/CODE-SET'
citizenships:
type: object
properties:
citizenship:
$ref: '#/components/schemas/CODE-SET_2'
phoneNumbers_2:
type: object
properties:
type:
$ref: '#/components/schemas/CODE-SET_2'
countryCode:
$ref: '#/components/schemas/TEXT_2'
areaCode:
$ref: '#/components/schemas/TEXT_2'
number:
$ref: '#/components/schemas/TEXT_2'
extension:
$ref: '#/components/schemas/TEXT_2'
validTo:
$ref: '#/components/schemas/DATE_2'
validFrom:
$ref: '#/components/schemas/DATE_2'
bestTimeToContact:
type: array
items:
type: object
properties:
day:
$ref: '#/components/schemas/CODE-SET_2'
startTime:
$ref: '#/components/schemas/TIME_2'
endTime:
$ref: '#/components/schemas/TIME_2'
allDay:
$ref: '#/components/schemas/BOOLEAN_2'
PostIdentityWsRequest_2:
type: object
properties:
identity:
$ref: '#/components/schemas/PostIdentityIdentity'
description: The identity to add.
responseIdentityFormatNames:
type: array
items:
type: string
uniqueItems: true
description: 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.
required:
- identity
description: adds a new identity to the LINK database
multipleBirthIndicator:
type: object
properties:
multipleBirthIndicator:
$ref: '#/components/schemas/BOOLEAN_2'
multipleBirthInteger:
$ref: '#/components/schemas/NUMBER_2'
birthPlurality:
$ref: '#/components/schemas/NUMBER_2'
guarantor:
type: object
properties:
relationship:
$ref: '#/components/schemas/CODE-SET_2'
firstName:
$ref: '#/components/schemas/TEXT_2'
middleName:
$ref: '#/components/schemas/TEXT_2'
lastName:
$ref: '#/components/schemas/TEXT_2'
suffix:
$ref: '#/components/schemas/TEXT_2'
dob:
$ref: '#/components/schemas/DATE_2'
ssn:
$ref: '#/components/schemas/TEXT_2'
addressLine1:
$ref: '#/components/schemas/TEXT_2'
addressLine2:
$ref: '#/components/schemas/TEXT_2'
city:
$ref: '#/components/schemas/TEXT_2'
state:
$ref: '#/components/schemas/TEXT_2'
zip:
$ref: '#/components/schemas/TEXT_2'
phone:
$ref: '#/components/schemas/TEXT_2'
onHold:
$ref: '#/components/schemas/BOOLEAN_2'
startDate:
$ref: '#/components/schemas/DATE_2'
endDate:
$ref: '#/components/schemas/DATE_2'
PostIdentitySource:
description: Source object used when posting a new identity. The customerMetaData field is deprecated and will be removed in a future version — do not include it in new integrations.
allOf:
- $ref: '#/components/schemas/Source_2'
- type: object
properties:
customerMetaData:
deprecated: true
description: '**Deprecated.** Customer metadata should no longer be passed inside the source object. This field will be removed in a future version.'
allOf:
- $ref: '#/components/schemas/CustomerMetaData'
TIME:
type: string
description: TIME data type, see documentation for more details.
legalStatus:
type: object
properties:
type:
$ref: '#/components/schemas/CODE-SET'
source:
$ref: '#/components/schemas/TEXT'
effectiveDate:
$ref: '#/components/schemas/DATE'
verificationDate:
$ref: '#/components/schemas/DATE'
jurisdiction:
$ref: '#/components/schemas/TEXT'
registrationCountry:
$ref: '#/components/schemas/CODE-SET'
authorizedOfficials:
type: object
properties:
title:
$ref: '#/components/schemas/TEXT'
prefix:
$ref: '#/components/schemas/TEXT'
first:
$ref: '#/components/schemas/TEXT'
middle:
$ref: '#/components/schemas/TEXT'
last:
$ref: '#/components/schemas/TEXT'
suffix:
$ref: '#/components/schemas/TEXT'
credential:
$ref: '#/components/schemas/TEXT'
phoneNumber:
$ref: '#/components/schemas/TEXT'
qualifications_2:
type: object
properties:
type:
$ref: '#/components/schemas/CODE-SET_2'
qualification:
$ref: '#/components/schemas/CODE-SET_2'
status:
$ref: '#/components/schemas/CODE-SET_2'
issuer:
$ref: '#/components/schemas/TEXT_2'
issueDate:
$ref: '#/components/schemas/DATE_2'
validFrom:
$ref: '#/components/schemas/DATE_2'
validTo:
$ref: '#/components/schemas/DATE_2'
bestTimeToContact:
type: object
properties:
day:
$ref: '#/components/schemas/CODE-SET'
startTime:
$ref: '#/components/schemas/TIME'
endTime:
$ref: '#/components/schemas/TIME'
allDay:
$ref: '#/components/schemas/BOOLEAN'
BOOLEAN_2:
type: boolean
description: BOOLEAN data type, see documentation for more details
Email:
type: object
properties:
sources:
type: array
items:
$ref: '#/components/schemas/Source_2'
description: The source for this cluster
type:
type: string
email:
type: string
validFrom:
type: string
format: date
validTo:
type: string
format: date
clusterStatus:
type: string
enum:
- ACTIVE
- INACTIVE
description: The current clusterStatus
DATE_2:
type: string
description: DATE data type, see documentation for more details
organizationNames:
type: object
properties:
legalBusinessName:
$ref: '#/components/schemas/TEXT'
otherOrgName:
$ref: '#/components/schemas/TEXT'
tradingName:
$ref: '#/components/schemas/TEXT'
parentOrgName:
$ref: '#/components/schemas/TEXT'
PostIdentityIdentity:
description: Identity payload used when posting a new identity. Extends the base Identity model with a sources array that associates the identity with one or more data sources.
allOf:
- $ref: '#/components/schemas/Identity_2'
- type: object
required:
- sources
properties:
sources:
type: array
minItems: 1
maxItems: 1
description: The data source that provided this identity. Exactly one source is required per request.
items:
$ref: '#/components/schemas/PostIdentitySource'
alternateIdentifiers:
type: object
properties:
description:
$ref: '#/components/schemas/TEXT'
type:
$ref: '#/components/schemas/CODE-SET'
value:
$ref: '#/components/schemas/TEXT'
status:
$ref: '#/components/schemas/BOOLEAN'
issuer:
$ref: '#/components/schemas/TEXT'
issueDate:
$ref: '#/components/schemas/DATE'
startDate:
$ref: '#/components/schemas/DATE'
endDate:
$ref: '#/components/schemas/DATE'
faxNumbers:
type: object
properties:
number:
$ref: '#/components/schemas/TEXT'
type:
$ref: '#/components/schemas/CODE-SET'
validFrom:
$ref: '#/components/schemas/DATE'
validTo:
$ref: '#/components/schemas/DATE'
ssns:
type: object
properties:
ssn:
$ref: '#/components/schemas/TEXT_2'
VerifiedAddress:
type: object
properties:
pmbDesignator:
type: string
zip:
type: string
secondaryNumber:
type: string
deliveryPoint:
type: string
country:
type: string
extraSecondaryDesignator:
type: string
streetPredirection:
type: string
city:
type: string
extraSecondaryNumber:
type: string
secondaryDesignator:
# --- truncated at 32 KB (60 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/verato/refs/heads/main/openapi/verato-postidentity-api-openapi.yml