OpenAssistantAPI
→

User API

Contacts

Contact management and bulk import

GET/contacts

List contacts

Query parameters

pageinteger
perPageinteger
limitinteger
userIdstring
statusstring
searchstring
qstring
scopestring
sourceTypestring
tagsstring

Responses

200Contacts
ok reqenumtrue
contacts reqobject[]
id reqstring
user reqstring
name reqstring | null
preferredNamestring | null
email reqstring
emailsobject[]
address reqstring
typeenumworkpersonalother
primaryboolean
sourcestring
phonesobject[]
number reqstring
typeenumworkmobilehomeother
primaryboolean
sourcestring
company reqobject | null
id reqstring
name reqstring
slug reqstring
domain reqstring | null
title reqstring | null
timezone reqstring | null
tzOffsetstring | null
photoUrlstring | null
website reqstring | null
bookingLink reqstring | null
socialobject
linkedInstring
xstring
otherstring
addressobject
line1string
line2string
citystring
statestring
zipstring
countrystring
enrichedAtstring | null
enrichmentVersioninteger
sourceobject | null
typeenummanualteammateteammate_archivedimportedemailimportapollocrmatshrisvoiceonboardingcalendarothernull
userIdstring | null
lastContactedAtstring | null
externalIdsobject[]
integration reqstring
externalId reqstring
syncedAtstring | null
propertiesobject
priorityinteger
inheritCompanyPriorityboolean
tagsstring[]
introducedBystring | null
scopeenumuserteam
teamstring | null
status reqstring
consumerobject | null
id reqstring
name reqstring | null
email reqstring | null
createdAt reqstring
updatedAt reqstring
assistantobject | null
namestring | null
emailstring | null
userIdentifierstring | null
sourceenuminternal-rosterdeclared-by-counterpartmanualnull
internalboolean
isMemberboolean
pageinteger
perPageinteger
totalinteger

Request

curl 'https://app.openassistant.us/api/contacts' \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "ok": true,
  "contacts": [
    {
      "id": "string",
      "user": "string",
      "name": "string",
      "email": "string",
      "company": {
        "id": "string",
        "name": "string",
        "slug": "string",
        "domain": "string"
      },
      "title": "string"
    }
  ]
}
POST/contacts

Create a contact

Request body

email reqstring
namestring
preferredNamestring
phonesobject[]
number reqstring
typeenummobileworkhomeother
primaryboolean
emailsobject[]
address reqstring
typeenumpersonalworkother
primaryboolean
companystring
titlestring
timezonestring
consumerEmailstring
sourcestring | object | null
externalIdsobject[]
integration reqstring
externalId reqstring
propertiesobject
scopeenumuserteam
teamstring
tagsstring[]
priorityinteger
inheritCompanyPriorityboolean

Responses

201Created
ok reqenumtrue
contact reqobject
id reqstring
user reqstring
name reqstring | null
preferredNamestring | null
email reqstring
emailsobject[]
address reqstring
typeenumworkpersonalother
primaryboolean
sourcestring
phonesobject[]
number reqstring
typeenumworkmobilehomeother
primaryboolean
sourcestring
company reqobject | null
id reqstring
name reqstring
slug reqstring
domain reqstring | null
title reqstring | null
timezone reqstring | null
tzOffsetstring | null
photoUrlstring | null
website reqstring | null
bookingLink reqstring | null
socialobject
linkedInstring
xstring
otherstring
addressobject
line1string
line2string
citystring
statestring
zipstring
countrystring
enrichedAtstring | null
enrichmentVersioninteger
sourceobject | null
typeenummanualteammateteammate_archivedimportedemailimportapollocrmatshrisvoiceonboardingcalendarothernull
userIdstring | null
lastContactedAtstring | null
externalIdsobject[]
integration reqstring
externalId reqstring
syncedAtstring | null
propertiesobject
priorityinteger
inheritCompanyPriorityboolean
tagsstring[]
introducedBystring | null
scopeenumuserteam
teamstring | null
status reqstring
consumerobject | null
id reqstring
name reqstring | null
email reqstring | null
createdAt reqstring
updatedAt reqstring
assistantobject | null
namestring | null
emailstring | null
userIdentifierstring | null
sourceenuminternal-rosterdeclared-by-counterpartmanualnull
internalboolean
isMemberboolean

Request

curl 'https://app.openassistant.us/api/contacts' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "email": "[email protected]"
}'

Response

{
  "ok": true,
  "contact": {
    "id": "string",
    "user": "string",
    "name": "string",
    "email": "string",
    "company": {
      "id": "string",
      "name": "string",
      "slug": "string",
      "domain": "string"
    },
    "title": "string"
  }
}
POST/contacts/bulk-tag

Tag or untag many contacts at once (portal-only)

Applies the tag add/remove lists to each visible contact. Invisible ids are returned in `failed[]`. Prime cannot call this endpoint — individual contact tagging goes through update_contact instead.

Request body

ids reqstring[]
addstring[]
removestring[]

Responses

200Bulk-tag result
ok reqenumtrue
bulkTag reqobject
ok reqenumtrue
updated reqinteger
total reqinteger
failed reqobject[]
id reqstring
reason reqstring

Request

curl 'https://app.openassistant.us/api/contacts/bulk-tag' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "ids": [
    "string"
  ]
}'

Response

{
  "ok": true,
  "bulkTag": {
    "ok": true,
    "updated": 0,
    "total": 0,
    "failed": [
      {
        "id": "string",
        "reason": "string"
      }
    ]
  }
}
POST/contacts/bulk-import

Bulk import contacts

Request body

contacts reqobject[]
email reqstring
namestring
preferredNamestring
phonestring
phonesobject[]
number reqstring
typeenummobileworkhomeother
primaryboolean
companystring
titlestring
timezonestring
emailsobject[]
address reqstring
typeenumpersonalworkother
primaryboolean
propertiesobject
tagsstring[]

Responses

200Import result
ok reqenumtrue
bulkImport reqobject
success reqboolean
total reqnumber
created reqnumber
updated reqnumber
skipped reqnumber
errors reqobject[]
indexnumber
emailstring
error reqstring

Request

curl 'https://app.openassistant.us/api/contacts/bulk-import' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "contacts": [
    {
      "email": "[email protected]"
    }
  ]
}'

Response

{
  "ok": true,
  "bulkImport": {
    "success": true,
    "total": 0,
    "created": 0,
    "updated": 0,
    "skipped": 0,
    "errors": [
      {
        "error": "string"
      }
    ]
  }
}
GET/contacts/{contactId}

Get a contact

Path parameters

contactId reqstring

Responses

200Contact
ok reqenumtrue
contact reqobject
idstring
userstring
namestring | null
preferredNamestring | null
emailstring
emailsobject[]
address reqstring
typeenumworkpersonalother
primaryboolean
sourcestring
phonesobject[]
number reqstring
typeenumworkmobilehomeother
primaryboolean
sourcestring
companyobject | null
id reqstring
name reqstring
slug reqstring
domain reqstring | null
titlestring | null
timezonestring | null
tzOffsetstring | null
photoUrlstring | null
websitestring | null
bookingLinkstring | null
socialobject
linkedInstring
xstring
otherstring
addressobject
line1string
line2string
citystring
statestring
zipstring
countrystring
enrichedAtstring | null
enrichmentVersioninteger
sourceobject | null
typeenummanualteammateteammate_archivedimportedemailimportapollocrmatshrisvoiceonboardingcalendarothernull
userIdstring | null
lastContactedAtstring | null
externalIdsobject[]
integration reqstring
externalId reqstring
syncedAtstring | null
propertiesobject
priorityinteger
inheritCompanyPriorityboolean
tagsstring[]
introducedBystring | null
scopeenumuserteam
teamstring | null
statusstring
consumerobject | null
id reqstring
name reqstring | null
email reqstring | null
createdAtstring
updatedAtstring
assistantobject | null
namestring | null
emailstring | null
userIdentifierstring | null
sourceenuminternal-rosterdeclared-by-counterpartmanualnull
internalboolean
isMemberboolean

Request

curl 'https://app.openassistant.us/api/contacts/<contactId>' \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "ok": true,
  "contact": {
    "id": "string",
    "user": "string",
    "name": "string",
    "email": "string",
    "company": {
      "id": "string",
      "name": "string",
      "slug": "string",
      "domain": "string"
    },
    "title": "string",
    "outgoingRelationships": [],
    "incomingRelationships": []
  }
}
PUT/contacts/{contactId}

Update a contact

Path parameters

contactId reqstring

Request body

namestring
preferredNamestring | null
phonesobject[]
number reqstring
typeenummobileworkhomeother
primaryboolean
companystring | null
titlestring | null
timezonestring
statusstring
websitestring | null
bookingLinkstring | null
introducedBystring | null
socialobject
linkedInstring
xstring
otherstring
addressobject
line1string
line2string
citystring
statestring
zipstring
countrystring
emailsobject[]
address reqstring
typeenumpersonalworkother
primaryboolean
lastContactedAtstring | null
enrichedAtstring | null
propertiesobject
scopeenumuserteam
teamstring | null
tagsstring[]
priorityinteger
inheritCompanyPriorityboolean

Responses

200Updated
ok reqenumtrue
contact reqobject
id reqstring
user reqstring
name reqstring | null
preferredNamestring | null
email reqstring
emailsobject[]
address reqstring
typeenumworkpersonalother
primaryboolean
sourcestring
phonesobject[]
number reqstring
typeenumworkmobilehomeother
primaryboolean
sourcestring
company reqobject | null
id reqstring
name reqstring
slug reqstring
domain reqstring | null
title reqstring | null
timezone reqstring | null
tzOffsetstring | null
photoUrlstring | null
website reqstring | null
bookingLink reqstring | null
socialobject
linkedInstring
xstring
otherstring
addressobject
line1string
line2string
citystring
statestring
zipstring
countrystring
enrichedAtstring | null
enrichmentVersioninteger
sourceobject | null
typeenummanualteammateteammate_archivedimportedemailimportapollocrmatshrisvoiceonboardingcalendarothernull
userIdstring | null
lastContactedAtstring | null
externalIdsobject[]
integration reqstring
externalId reqstring
syncedAtstring | null
propertiesobject
priorityinteger
inheritCompanyPriorityboolean
tagsstring[]
introducedBystring | null
scopeenumuserteam
teamstring | null
status reqstring
consumerobject | null
id reqstring
name reqstring | null
email reqstring | null
createdAt reqstring
updatedAt reqstring
assistantobject | null
namestring | null
emailstring | null
userIdentifierstring | null
sourceenuminternal-rosterdeclared-by-counterpartmanualnull
internalboolean
isMemberboolean

Request

curl 'https://app.openassistant.us/api/contacts/<contactId>' \
  -X PUT \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "preferredName": "string",
  "phones": [
    {
      "number": "string"
    }
  ],
  "company": "string"
}'

Response

{
  "ok": true,
  "contact": {
    "id": "string",
    "user": "string",
    "name": "string",
    "email": "string",
    "company": {
      "id": "string",
      "name": "string",
      "slug": "string",
      "domain": "string"
    },
    "title": "string"
  }
}
DELETE/contacts/{contactId}

Delete a contact

Path parameters

contactId reqstring

Responses

200Deleted
ok reqenumtrue
contact reqobject
id reqstring
deletedboolean
messagestring

Request

curl 'https://app.openassistant.us/api/contacts/<contactId>' \
  -X DELETE \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "ok": true,
  "contact": {
    "id": "string"
  }
}
POST/contacts/{contactId}/merge

Merge two contacts

Path parameters

contactId reqstring

Request body

mergeContactId reqstring

Responses

200Merged
ok reqenumtrue
contact reqobject
idstring
userstring
namestring | null
preferredNamestring | null
emailstring
emailsobject[]
address reqstring
typeenumworkpersonalother
primaryboolean
sourcestring
phonesobject[]
number reqstring
typeenumworkmobilehomeother
primaryboolean
sourcestring
companyobject | null
id reqstring
name reqstring
slug reqstring
domain reqstring | null
titlestring | null
timezonestring | null
tzOffsetstring | null
photoUrlstring | null
websitestring | null
bookingLinkstring | null
socialobject
linkedInstring
xstring
otherstring
addressobject
line1string
line2string
citystring
statestring
zipstring
countrystring
enrichedAtstring | null
enrichmentVersioninteger
sourceobject | null
typeenummanualteammateteammate_archivedimportedemailimportapollocrmatshrisvoiceonboardingcalendarothernull
userIdstring | null
lastContactedAtstring | null
externalIdsobject[]
integration reqstring
externalId reqstring
syncedAtstring | null
propertiesobject
priorityinteger
inheritCompanyPriorityboolean
tagsstring[]
introducedBystring | null
scopeenumuserteam
teamstring | null
statusstring
consumerobject | null
id reqstring
name reqstring | null
email reqstring | null
createdAtstring
updatedAtstring
assistantobject | null
namestring | null
emailstring | null
userIdentifierstring | null
sourceenuminternal-rosterdeclared-by-counterpartmanualnull
internalboolean
isMemberboolean

Request

curl 'https://app.openassistant.us/api/contacts/<contactId>/merge' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "mergeContactId": "string"
}'

Response

{
  "ok": true,
  "contact": {
    "id": "string",
    "user": "string",
    "name": "string",
    "email": "string",
    "company": {
      "id": "string",
      "name": "string",
      "slug": "string",
      "domain": "string"
    },
    "title": "string",
    "merged": true,
    "mergedContactId": "string"
  }
}
POST/contacts/{contactId}/relationships

Create a contact relationship link

Path parameters

contactId reqstring

Request body

toContactId reqstring
type reqenumcoordinatespartnerassistantparentother
rolestring
isPrimaryboolean
notesstring

Responses

200Created
ok reqenumtrue
relationship reqobject
id reqstring
account reqstring
user reqstring
fromContact reqstring | object
toContact reqstring | object
type reqenumcoordinatespartnerassistantparentother
rolestring | null
isPrimaryboolean
notesstring | null
createdAt reqstring
updatedAt reqstring

Request

curl 'https://app.openassistant.us/api/contacts/<contactId>/relationships' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "toContactId": "string",
  "type": "coordinates"
}'

Response

{
  "ok": true,
  "relationship": {
    "id": "string",
    "account": "string",
    "user": "string",
    "fromContact": "string",
    "toContact": "string",
    "type": "coordinates"
  }
}
PATCH/contacts/{contactId}/relationships/{relationshipId}

Update a contact relationship (role, isPrimary, notes)

Path parameters

contactId reqstring
relationshipId reqstring

Request body

rolestring | null
isPrimaryboolean
notesstring | null

Responses

200Updated
ok reqenumtrue
relationship reqobject
id reqstring
account reqstring
user reqstring
fromContact reqstring | object
toContact reqstring | object
type reqenumcoordinatespartnerassistantparentother
rolestring | null
isPrimaryboolean
notesstring | null
createdAt reqstring
updatedAt reqstring

Request

curl 'https://app.openassistant.us/api/contacts/<contactId>/relationships/<relationshipId>' \
  -X PATCH \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "role": "string",
  "isPrimary": true,
  "notes": "string"
}'

Response

{
  "ok": true,
  "relationship": {
    "id": "string",
    "account": "string",
    "user": "string",
    "fromContact": "string",
    "toContact": "string",
    "type": "coordinates"
  }
}
DELETE/contacts/{contactId}/relationships/{relationshipId}

Delete a contact relationship link

Path parameters

contactId reqstring
relationshipId reqstring

Responses

200Deleted
ok reqenumtrue
relationship reqobject
id reqstring
deletedboolean
messagestring

Request

curl 'https://app.openassistant.us/api/contacts/<contactId>/relationships/<relationshipId>' \
  -X DELETE \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "ok": true,
  "relationship": {
    "id": "string"
  }
}
PUT/contacts/{contactId}/external-ids/{integration}

Upsert an external system ID

Path parameters

contactId reqstring
integration reqstring

Request body

externalId reqstring

Responses

200Updated
ok reqenumtrue
contact reqobject
id reqstring
user reqstring
name reqstring | null
preferredNamestring | null
email reqstring
emailsobject[]
address reqstring
typeenumworkpersonalother
primaryboolean
sourcestring
phonesobject[]
number reqstring
typeenumworkmobilehomeother
primaryboolean
sourcestring
company reqobject | null
id reqstring
name reqstring
slug reqstring
domain reqstring | null
title reqstring | null
timezone reqstring | null
tzOffsetstring | null
photoUrlstring | null
website reqstring | null
bookingLink reqstring | null
socialobject
linkedInstring
xstring
otherstring
addressobject
line1string
line2string
citystring
statestring
zipstring
countrystring
enrichedAtstring | null
enrichmentVersioninteger
sourceobject | null
typeenummanualteammateteammate_archivedimportedemailimportapollocrmatshrisvoiceonboardingcalendarothernull
userIdstring | null
lastContactedAtstring | null
externalIdsobject[]
integration reqstring
externalId reqstring
syncedAtstring | null
propertiesobject
priorityinteger
inheritCompanyPriorityboolean
tagsstring[]
introducedBystring | null
scopeenumuserteam
teamstring | null
status reqstring
consumerobject | null
id reqstring
name reqstring | null
email reqstring | null
createdAt reqstring
updatedAt reqstring
assistantobject | null
namestring | null
emailstring | null
userIdentifierstring | null
sourceenuminternal-rosterdeclared-by-counterpartmanualnull
internalboolean
isMemberboolean

Request

curl 'https://app.openassistant.us/api/contacts/<contactId>/external-ids/<integration>' \
  -X PUT \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "externalId": "string"
}'

Response

{
  "ok": true,
  "contact": {
    "id": "string",
    "user": "string",
    "name": "string",
    "email": "string",
    "company": {
      "id": "string",
      "name": "string",
      "slug": "string",
      "domain": "string"
    },
    "title": "string"
  }
}
GET/contacts/by-external-id/{integration}/{externalId}

Find contact by external system ID

Path parameters

integration reqstring
externalId reqstring

Responses

200Contact
ok reqenumtrue
contact reqobject
id reqstring
user reqstring
name reqstring | null
preferredNamestring | null
email reqstring
emailsobject[]
address reqstring
typeenumworkpersonalother
primaryboolean
sourcestring
phonesobject[]
number reqstring
typeenumworkmobilehomeother
primaryboolean
sourcestring
company reqobject | null
id reqstring
name reqstring
slug reqstring
domain reqstring | null
title reqstring | null
timezone reqstring | null
tzOffsetstring | null
photoUrlstring | null
website reqstring | null
bookingLink reqstring | null
socialobject
linkedInstring
xstring
otherstring
addressobject
line1string
line2string
citystring
statestring
zipstring
countrystring
enrichedAtstring | null
enrichmentVersioninteger
sourceobject | null
typeenummanualteammateteammate_archivedimportedemailimportapollocrmatshrisvoiceonboardingcalendarothernull
userIdstring | null
lastContactedAtstring | null
externalIdsobject[]
integration reqstring
externalId reqstring
syncedAtstring | null
propertiesobject
priorityinteger
inheritCompanyPriorityboolean
tagsstring[]
introducedBystring | null
scopeenumuserteam
teamstring | null
status reqstring
consumerobject | null
id reqstring
name reqstring | null
email reqstring | null
createdAt reqstring
updatedAt reqstring
assistantobject | null
namestring | null
emailstring | null
userIdentifierstring | null
sourceenuminternal-rosterdeclared-by-counterpartmanualnull
internalboolean
isMemberboolean

Request

curl 'https://app.openassistant.us/api/contacts/by-external-id/<integration>/<externalId>' \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "ok": true,
  "contact": {
    "id": "string",
    "user": "string",
    "name": "string",
    "email": "string",
    "company": {
      "id": "string",
      "name": "string",
      "slug": "string",
      "domain": "string"
    },
    "title": "string"
  }
}
GET/property-definitions

List property definitions

Query parameters

entityTypestring

Responses

200Property definitions
ok reqenumtrue
propertyDefinitions reqobject[]
id reqstring
account reqstring
user reqstring
entityType reqenumcontactcompany
key reqstring
label reqstring
type reqenumtextnumberdatebooleanselecturl
options reqstring[]
showForAll reqboolean
scopeenumuserteam
teamstring | null
createdAtstring
updatedAtstring
pageinteger
perPageinteger
totalinteger

Request

curl 'https://app.openassistant.us/api/property-definitions' \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "ok": true,
  "propertyDefinitions": [
    {
      "id": "507f1f77bcf86cd799439011",
      "account": "507f1f77bcf86cd799439011",
      "user": "507f1f77bcf86cd799439011",
      "entityType": "contact",
      "key": "string",
      "label": "string"
    }
  ]
}
PUT/property-definitions/{entityType}/{key}

Upsert a property definition

Path parameters

entityType reqstring
key reqstring

Request body

labelstring
typeenumtextnumberdatebooleanselecturl
optionsstring[]
showForAllboolean
scopeenumuserteam
teamstring | null

Responses

200Property definition
ok reqenumtrue
propertyDefinition reqobject
id reqstring
account reqstring
user reqstring
entityType reqenumcontactcompany
key reqstring
label reqstring
type reqenumtextnumberdatebooleanselecturl
options reqstring[]
showForAll reqboolean
scopeenumuserteam
teamstring | null
createdAtstring
updatedAtstring

Request

curl 'https://app.openassistant.us/api/property-definitions/<entityType>/<key>' \
  -X PUT \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "label": "string",
  "type": "text",
  "options": [
    "string"
  ],
  "showForAll": true
}'

Response

{
  "ok": true,
  "propertyDefinition": {
    "id": "507f1f77bcf86cd799439011",
    "account": "507f1f77bcf86cd799439011",
    "user": "507f1f77bcf86cd799439011",
    "entityType": "contact",
    "key": "string",
    "label": "string"
  }
}