Skip to content

Create or update a contact by its id in your system

PUT
/products/{productId}/sync/contacts/{source}/{externalId}
curl --request PUT \
--url https://api.motenya.app/v1/products/example/sync/contacts/erp/C-1042 \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "name": "example", "emails": [ "example" ], "phone": "example", "language": "example", "tags": [ "example" ], "custom": "example", "clientExternalIds": [ "example" ] }'

Idempotent: the first call creates it, later calls with the same source and external id update the fields sent. References to other records can use their ids in the same source (…ExternalId). A new external id first matches a contact by any of its emails, so people already in the CRM (from tickets, say) are not duplicated. Emails are added, never removed.

Requires crm:write.

productId
required
string
>= 1 characters <= 64 characters
source
required

The system the record comes from, named by you: e.g. magento2:casa-verde, stripe, erp.

string
/^[a-z0-9][a-z0-9._:-]{0,63}$/

Example

erp

The system the record comes from, named by you: e.g. magento2:casa-verde, stripe, erp.

externalId
required

The record’s id in that system.

string
>= 1 characters <= 128 characters

Example

C-1042

The record’s id in that system.

Media typeapplication/json
object
name
string | null
<= 200 characters
emails

Primary first; normalized to lowercase. Unique within the product.

Array<string> | null
<= 20 items
phone
string | null
<= 50 characters
language
string | null
<= 16 characters
tags
Array<string> | null
<= 30 items
custom

Custom field values keyed by field key; null clears one. See GET /products/{productId}/custom-fields.

object | null
clientExternalIds

Clients (by their ids in the same source) to link the contact to.

Array<string> | null
<= 20 items

Example generated

{
"name": "example",
"emails": [
"example"
],
"phone": "example",
"language": "example",
"tags": [
"example"
],
"custom": "example",
"clientExternalIds": [
"example"
]
}

Success

Media typeapplication/json
object
entity
required
string
id
required
string
>= 1 characters <= 64 characters
created
required

False when an existing record was updated (found by external id, or matched).

boolean
record
required
object
id
required
string
>= 1 characters <= 64 characters
name
required
string | null
emails
required
Array<string>
phone
required
string | null
language
required
string | null
tags
required
Array<string>
custom
required
object
key
additional properties
source
required
string
externalId
required
string | null
clients
required
Array<object>
object
clientId
required
string
>= 1 characters <= 64 characters
name
required
string
kind
required
string
Allowed values: company individual
role
required
string | null
createdAt
required
string
updatedAt
required
string
key
additional properties

Example

{
"record": {
"clients": [
{
"kind": "company"
}
]
}
}

Invalid request

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string
field
string
details
Array<object>
object
code
required
string
message
required
string
field
string

Example

{
"error": {
"code": "SLUG_TAKEN"
}
}

Missing, invalid, revoked or expired API key

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string
field
string
details
Array<object>
object
code
required
string
message
required
string
field
string

Example

{
"error": {
"code": "SLUG_TAKEN"
}
}

Missing scope, API turned off, published article without publish scope, or account suspended

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string
field
string
details
Array<object>
object
code
required
string
message
required
string
field
string

Example

{
"error": {
"code": "SLUG_TAKEN"
}
}

Not found, or outside the knowledge bases this key may use

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string
field
string
details
Array<object>
object
code
required
string
message
required
string
field
string

Example

{
"error": {
"code": "SLUG_TAKEN"
}
}

Slug or translation already exists

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string
field
string
details
Array<object>
object
code
required
string
message
required
string
field
string

Example

{
"error": {
"code": "SLUG_TAKEN"
}
}

Rejected by validation (e.g. unknown language or category)

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string
field
string
details
Array<object>
object
code
required
string
message
required
string
field
string

Example

{
"error": {
"code": "SLUG_TAKEN"
}
}

Rate limited; see Retry-After

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string
field
string
details
Array<object>
object
code
required
string
message
required
string
field
string

Example

{
"error": {
"code": "SLUG_TAKEN"
}
}

Internal error