Create contacts

POST

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"
  }
]
'

import requests

url = "https://api.nova.net/v1/contacts"

payload = [
    {
        "name": "Jane Doe",
        "email": "jane.doe@example.com",
        "external_reference": "contact-123"
    }
]
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify([
    {
      name: 'Jane Doe',
      email: 'jane.doe@example.com',
      external_reference: 'contact-123'
    }
  ])
};

fetch('https://api.nova.net/v1/contacts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.nova.net/v1/contacts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    [
        'name' => 'Jane Doe',
        'email' => 'jane.doe@example.com',
        'external_reference' => 'contact-123'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.nova.net/v1/contacts"

	payload := strings.NewReader("[\n  {\n    \"name\": \"Jane Doe\",\n    \"email\": \"jane.doe@example.com\",\n    \"external_reference\": \"contact-123\"\n  }\n]")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.nova.net/v1/contacts")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("[\n  {\n    \"name\": \"Jane Doe\",\n    \"email\": \"jane.doe@example.com\",\n    \"external_reference\": \"contact-123\"\n  }\n]")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.nova.net/v1/contacts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "[\n  {\n    \"name\": \"Jane Doe\",\n    \"email\": \"jane.doe@example.com\",\n    \"external_reference\": \"contact-123\"\n  }\n]"

response = http.request(request)
puts response.read_body

{
  "object": "list",
  "data": [
    {
      "object": "contact",
      "livemode": true,
      "id": "cnt_tSfCZrNE8O3c4QATSkzuCljMZ2DI",
      "name": "Jane Doe",
      "email": "jane.doe@example.com",
      "external_reference": "contact-123"
    }
  ],
  "next_page_url": "/v1/contacts?page=page_5dr8SFDbv7rZ2aj4&limit=10",
  "previous_page_url": "/v1/contacts?page_before=page_8VtqLBv3xJpY7mk2&limit=10",
  "has_more": true,
  "url": "/v1/contacts"
}

{
  "object": "error",
  "type": "invalid_request_error",
  "code": "parameter_invalid",
  "message": "The 'limit' parameter must be between 1 and 100.",
  "status": 400,
  "invalid-params": [
    {
      "code": "parameter_invalid",
      "name": "body.[0].limit",
      "value": 200,
      "reason": "out of range"
    }
  ]
}

{
  "object": "error",
  "type": "invalid_request_error",
  "code": "parameter_invalid",
  "message": "The 'limit' parameter must be between 1 and 100.",
  "status": 400,
  "invalid-params": [
    {
      "code": "parameter_invalid",
      "name": "body.[0].limit",
      "value": 200,
      "reason": "out of range"
    }
  ]
}

{
  "object": "error",
  "type": "invalid_request_error",
  "code": "parameter_invalid",
  "message": "The 'limit' parameter must be between 1 and 100.",
  "status": 400,
  "invalid-params": [
    {
      "code": "parameter_invalid",
      "name": "body.[0].limit",
      "value": 200,
      "reason": "out of range"
    }
  ]
}

{
  "object": "error",
  "type": "invalid_request_error",
  "code": "parameter_invalid",
  "message": "The 'limit' parameter must be between 1 and 100.",
  "status": 400,
  "invalid-params": [
    {
      "code": "parameter_invalid",
      "name": "body.[0].limit",
      "value": 200,
      "reason": "out of range"
    }
  ]
}

{
  "object": "error",
  "type": "invalid_request_error",
  "code": "parameter_invalid",
  "message": "The 'limit' parameter must be between 1 and 100.",
  "status": 400,
  "invalid-params": [
    {
      "code": "parameter_invalid",
      "name": "body.[0].limit",
      "value": 200,
      "reason": "out of range"
    }
  ]
}

{
  "object": "error",
  "type": "invalid_request_error",
  "code": "parameter_invalid",
  "message": "The 'limit' parameter must be between 1 and 100.",
  "status": 400,
  "invalid-params": [
    {
      "code": "parameter_invalid",
      "name": "body.[0].limit",
      "value": 200,
      "reason": "out of range"
    }
  ]
}

{
  "object": "error",
  "type": "invalid_request_error",
  "code": "parameter_invalid",
  "message": "The 'limit' parameter must be between 1 and 100.",
  "status": 400,
  "invalid-params": [
    {
      "code": "parameter_invalid",
      "name": "body.[0].limit",
      "value": 200,
      "reason": "out of range"
    }
  ]
}

{
  "object": "error",
  "type": "invalid_request_error",
  "code": "parameter_invalid",
  "message": "The 'limit' parameter must be between 1 and 100.",
  "status": 400,
  "invalid-params": [
    {
      "code": "parameter_invalid",
      "name": "body.[0].limit",
      "value": 200,
      "reason": "out of range"
    }
  ]
}

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_EkzhrUc3U6C0UbxNBlK7WLz51ofT"

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 422 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"

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.

Show child attributes

next_page_url

string | null

required

URL for the next page of the list, or null when there are no more pages.

Example:

"/v1/contacts?page=page_5dr8SFDbv7rZ2aj4&limit=10"

previous_page_url

string | null

required

URL for the previous page of the list, or null when there are none.

Example:

"/v1/contacts?page_before=page_8VtqLBv3xJpY7mk2&limit=10"

has_more

boolean

required

deprecated

Whether there are more items available after this page. Deprecated: next_page_url is non-null exactly when more pages exist.

url

string

required

deprecated

The URL for this list endpoint. Deprecated: follow next_page_url / previous_page_url to paginate.

Example:

"/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"
  }
]
'

import requests

url = "https://api.nova.net/v1/contacts"

payload = [
    {
        "name": "Jane Doe",
        "email": "jane.doe@example.com",
        "external_reference": "contact-123"
    }
]
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify([
    {
      name: 'Jane Doe',
      email: 'jane.doe@example.com',
      external_reference: 'contact-123'
    }
  ])
};

fetch('https://api.nova.net/v1/contacts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.nova.net/v1/contacts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    [
        'name' => 'Jane Doe',
        'email' => 'jane.doe@example.com',
        'external_reference' => 'contact-123'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.nova.net/v1/contacts"

	payload := strings.NewReader("[\n  {\n    \"name\": \"Jane Doe\",\n    \"email\": \"jane.doe@example.com\",\n    \"external_reference\": \"contact-123\"\n  }\n]")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.nova.net/v1/contacts")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("[\n  {\n    \"name\": \"Jane Doe\",\n    \"email\": \"jane.doe@example.com\",\n    \"external_reference\": \"contact-123\"\n  }\n]")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.nova.net/v1/contacts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "[\n  {\n    \"name\": \"Jane Doe\",\n    \"email\": \"jane.doe@example.com\",\n    \"external_reference\": \"contact-123\"\n  }\n]"

response = http.request(request)
puts response.read_body

{
  "object": "list",
  "data": [
    {
      "object": "contact",
      "livemode": true,
      "id": "cnt_tSfCZrNE8O3c4QATSkzuCljMZ2DI",
      "name": "Jane Doe",
      "email": "jane.doe@example.com",
      "external_reference": "contact-123"
    }
  ],
  "next_page_url": "/v1/contacts?page=page_5dr8SFDbv7rZ2aj4&limit=10",
  "previous_page_url": "/v1/contacts?page_before=page_8VtqLBv3xJpY7mk2&limit=10",
  "has_more": true,
  "url": "/v1/contacts"
}

{
  "object": "error",
  "type": "invalid_request_error",
  "code": "parameter_invalid",
  "message": "The 'limit' parameter must be between 1 and 100.",
  "status": 400,
  "invalid-params": [
    {
      "code": "parameter_invalid",
      "name": "body.[0].limit",
      "value": 200,
      "reason": "out of range"
    }
  ]
}

{
  "object": "error",
  "type": "invalid_request_error",
  "code": "parameter_invalid",
  "message": "The 'limit' parameter must be between 1 and 100.",
  "status": 400,
  "invalid-params": [
    {
      "code": "parameter_invalid",
      "name": "body.[0].limit",
      "value": 200,
      "reason": "out of range"
    }
  ]
}

{
  "object": "error",
  "type": "invalid_request_error",
  "code": "parameter_invalid",
  "message": "The 'limit' parameter must be between 1 and 100.",
  "status": 400,
  "invalid-params": [
    {
      "code": "parameter_invalid",
      "name": "body.[0].limit",
      "value": 200,
      "reason": "out of range"
    }
  ]
}

{
  "object": "error",
  "type": "invalid_request_error",
  "code": "parameter_invalid",
  "message": "The 'limit' parameter must be between 1 and 100.",
  "status": 400,
  "invalid-params": [
    {
      "code": "parameter_invalid",
      "name": "body.[0].limit",
      "value": 200,
      "reason": "out of range"
    }
  ]
}

{
  "object": "error",
  "type": "invalid_request_error",
  "code": "parameter_invalid",
  "message": "The 'limit' parameter must be between 1 and 100.",
  "status": 400,
  "invalid-params": [
    {
      "code": "parameter_invalid",
      "name": "body.[0].limit",
      "value": 200,
      "reason": "out of range"
    }
  ]
}

{
  "object": "error",
  "type": "invalid_request_error",
  "code": "parameter_invalid",
  "message": "The 'limit' parameter must be between 1 and 100.",
  "status": 400,
  "invalid-params": [
    {
      "code": "parameter_invalid",
      "name": "body.[0].limit",
      "value": 200,
      "reason": "out of range"
    }
  ]
}

{
  "object": "error",
  "type": "invalid_request_error",
  "code": "parameter_invalid",
  "message": "The 'limit' parameter must be between 1 and 100.",
  "status": 400,
  "invalid-params": [
    {
      "code": "parameter_invalid",
      "name": "body.[0].limit",
      "value": 200,
      "reason": "out of range"
    }
  ]
}

{
  "object": "error",
  "type": "invalid_request_error",
  "code": "parameter_invalid",
  "message": "The 'limit' parameter must be between 1 and 100.",
  "status": 400,
  "invalid-params": [
    {
      "code": "parameter_invalid",
      "name": "body.[0].limit",
      "value": 200,
      "reason": "out of range"
    }
  ]
}

Distributions

Payment Instructions

Entities

Contacts

Financial Accounts

Authorizations

Headers

Body

Response