Skip to main content
POST
/
v1
/
contacts
Create contacts
curl --request POST \
  --url https://api.nova.net/v1/contacts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
[
  {
    "name": "Jane Doe",
    "email": "jane.doe@example.com",
    "external_reference": "contact-123"
  }
]
'
{
  "object": "list",
  "data": [
    {
      "object": "contact",
      "livemode": true,
      "id": "cnt_tSfCZrNE8O3c4QATSkzuCljMZ2DI",
      "name": "Jane Doe",
      "email": "jane.doe@example.com",
      "external_reference": "contact-123"
    }
  ],
  "has_more": true,
  "url": "/v1/contacts"
}

Authorizations

​
Authorization
string
header
required

OAuth2 client_credentials grant for server-to-server access. Onboard via your Nova admin to receive a client_id and client_secret, then POST /oauth/token to exchange them for a short-lived access token. Send the token as Authorization: Bearer <access_token> on every authenticated request. Tokens expire after 3600 seconds — refresh by re-exchanging credentials.

Headers

​
X-Organization-Id
string

ID of the organization the request acts on. Optional when the access token is bound to a specific organization, or when the integration has access to exactly one organization.

Pattern: ^org_[A-Za-z0-9]+$
Example:

"org_Xk7d2pQR9m3nBwYz"

​
Idempotency-Key
string

Supply a unique key to make a mutating request safely retryable. Any retry that sends the same key returns that stored response without performing the operation again.

  • Retention: keys are kept for 24 hours. Within that window a retry replays the original response.
  • Same key, different request: reusing a key with a different request body returns a 409 with code idempotency_mismatch. Use a fresh key for each distinct operation.
  • Still processing: if the first request has not finished, a retry returns 409 with code conflict (wait briefly and retry).
  • Server or transient errors (5xx, 408, 429) are not stored, so you may retry with the same key and the operation will be attempted again.

Only applies to POST, PUT, PATCH, and DELETE; ignored on reads.

Body

application/json
Minimum array length: 1
​
name
string
required

Full legal name

Required string length: 1 - 255
Example:

"Jane Doe"

​
email
string<email>
required

Email address

Example:

"jane.doe@example.com"

​
external_reference
string | null

Your own identifier for this contact

Example:

"contact-123"

Response

Contacts created

​
object
enum<string>
required

Object type identifier.

Available options:
list
Example:

"list"

​
data
object[]
required

The page of items.

​
has_more
boolean
required

Whether there are more items available after this page.

​
url
string
required

The URL for this list endpoint.

Example:

"/v1/contacts"