Create contact

Create contact

curl --request POST \
  --url https://api.routera.io/contacts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "fields": {
    "external_id": "ext-001",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "email": "ada@example.com"
  }
}
'

import requests

url = "https://api.routera.io/contacts"

payload = { "fields": {
        "external_id": "ext-001",
        "first_name": "Ada",
        "last_name": "Lovelace",
        "email": "ada@example.com"
    } }
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({
    fields: {
      external_id: 'ext-001',
      first_name: 'Ada',
      last_name: 'Lovelace',
      email: 'ada@example.com'
    }
  })
};

fetch('https://api.routera.io/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.routera.io/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([
    'fields' => [
        'external_id' => 'ext-001',
        'first_name' => 'Ada',
        'last_name' => 'Lovelace',
        'email' => 'ada@example.com'
    ]
  ]),
  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.routera.io/contacts"

	payload := strings.NewReader("{\n  \"fields\": {\n    \"external_id\": \"ext-001\",\n    \"first_name\": \"Ada\",\n    \"last_name\": \"Lovelace\",\n    \"email\": \"ada@example.com\"\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.routera.io/contacts")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"fields\": {\n    \"external_id\": \"ext-001\",\n    \"first_name\": \"Ada\",\n    \"last_name\": \"Lovelace\",\n    \"email\": \"ada@example.com\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.routera.io/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  \"fields\": {\n    \"external_id\": \"ext-001\",\n    \"first_name\": \"Ada\",\n    \"last_name\": \"Lovelace\",\n    \"email\": \"ada@example.com\"\n  }\n}"

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

{
  "id": "<string>",
  "external_id": "<string>",
  "first_name": "<string>",
  "last_name": "<string>",
  "email": "<string>",
  "contact_owner": "jane@example.com",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "archived": true,
  "archived_by": "<string>"
}

{
  "message": "<string>",
  "error": true,
  "field": "<string>"
}

{
  "message": "<string>",
  "error": true,
  "field": "<string>"
}

{
  "message": "<string>",
  "error": true,
  "field": "<string>"
}

{
  "message": "<string>",
  "error": true,
  "field": "<string>"
}

POST

contacts

Create contact

curl --request POST \
  --url https://api.routera.io/contacts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "fields": {
    "external_id": "ext-001",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "email": "ada@example.com"
  }
}
'

import requests

url = "https://api.routera.io/contacts"

payload = { "fields": {
        "external_id": "ext-001",
        "first_name": "Ada",
        "last_name": "Lovelace",
        "email": "ada@example.com"
    } }
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({
    fields: {
      external_id: 'ext-001',
      first_name: 'Ada',
      last_name: 'Lovelace',
      email: 'ada@example.com'
    }
  })
};

fetch('https://api.routera.io/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.routera.io/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([
    'fields' => [
        'external_id' => 'ext-001',
        'first_name' => 'Ada',
        'last_name' => 'Lovelace',
        'email' => 'ada@example.com'
    ]
  ]),
  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.routera.io/contacts"

	payload := strings.NewReader("{\n  \"fields\": {\n    \"external_id\": \"ext-001\",\n    \"first_name\": \"Ada\",\n    \"last_name\": \"Lovelace\",\n    \"email\": \"ada@example.com\"\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.routera.io/contacts")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"fields\": {\n    \"external_id\": \"ext-001\",\n    \"first_name\": \"Ada\",\n    \"last_name\": \"Lovelace\",\n    \"email\": \"ada@example.com\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.routera.io/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  \"fields\": {\n    \"external_id\": \"ext-001\",\n    \"first_name\": \"Ada\",\n    \"last_name\": \"Lovelace\",\n    \"email\": \"ada@example.com\"\n  }\n}"

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

{
  "id": "<string>",
  "external_id": "<string>",
  "first_name": "<string>",
  "last_name": "<string>",
  "email": "<string>",
  "contact_owner": "jane@example.com",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "archived": true,
  "archived_by": "<string>"
}

{
  "message": "<string>",
  "error": true,
  "field": "<string>"
}

{
  "message": "<string>",
  "error": true,
  "field": "<string>"
}

{
  "message": "<string>",
  "error": true,
  "field": "<string>"
}

{
  "message": "<string>",
  "error": true,
  "field": "<string>"
}

Endpoint

POST https://api.routera.io/contacts

Route: /contacts
Authentication: Bearer JWT

Request body

The body is a JSON object with a single fields property. Each key inside fields is a field internal_name (the same names returned in GET responses, not nested under fields in the response). Include every field you want to set on the new record.

{
  "fields": {
    "external_id": "ext-001",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "email": "ada@example.com"
  }
}

Key	Description
`fields`	Required. Map of `internal_name` → value for this object type.
`fields.external_id`	Optional. External identifier for sync with outside systems.

Custom fields configured in your account use the same key names inside fields.

Required on create: At least one of email, first_name, or last_name. See API introduction for field types and validation rules.

Default response fields

201 returns a flat object with these properties:

Property	Description
`id`	Internal object ID
`first_name`	Custom or system field (flat on the object)
`last_name`	Custom or system field (flat on the object)
`email`	Custom or system field (flat on the object)
`contact_owner`	Assigned owner email
`external_id`	External identifier (nullable)
`archived`	`false` when active; ISO timestamp when archived

created_at and updated_at are always included in every response (ISO 8601 UTC), even when not listed above. When an object is archived, archived_by is also included automatically.

Response example

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "external_id": "ext-001",
  "created_at": "2026-05-01T10:00:00.000Z",
  "updated_at": "2026-05-28T12:00:00.000Z",
  "archived": false,
  "first_name": "Ada",
  "last_name": "Lovelace",
  "email": "ada@example.com",
  "contact_owner": "jane@example.com"
}

Errors

Status	When
`400`	Invalid JSON body, unknown field name, validation failure, or forbidden system field
`401`	Missing account context
`409`	Duplicate active record (`email`, `website_url`, or `external_id`)
`500`	Internal server error

Authorizations

Authorization

string

header

required

Bearer JWT with valid account context.

Body

application/json

Write payload for POST create and PATCH update. Keys inside fields match field internal names returned in GET responses.

fields

object

required

Field values keyed by internal_name. Custom account fields use the same key names.

Hide child attributes

fields.external_id

string

Optional external identifier for sync with outside systems

Example:

"ext-001"

fields.first_name

string

Value for first_name (field internal_name)

Example:

"Ada"

fields.last_name

string

Value for last_name (field internal_name)

Example:

"Lovelace"

fields.email

string

Value for email (field internal_name)

Example:

"ada@example.com"

Response

Created

Flat JSON object; custom fields at top level alongside id and external_id. created_at and updated_at are always present.

string

external_id

string | null

first_name

string | null

last_name

string | null

contact_owner

string | null

Assigned owner email

Example:

"jane@example.com"

created_at

string<date-time>

updated_at

string<date-time>

archived

false when active, or ISO timestamp when archived

archived_by

string

Present when archived

List contacts Get contact by ID

Overview

Authentication

Contacts

Companies

Deals

Tickets

Routers

Dispatch

Endpoint

Request body

Default response fields

Response example

Errors

Authorizations

Body

Response

​Endpoint

​Request body

​Default response fields

​Response example

​Errors

Authorizations

Body

Response

Endpoint

Request body

Default response fields

Response example

Errors