Skip to main content
POST
/
contacts
Create Contact
curl --request POST \
  --url https://api.clemta.com/contacts \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "type": "customer",
  "full_name": "<string>",
  "email": "[email protected]",
  "company_id": "<string>",
  "status": "<string>",
  "description": "<string>",
  "cc_emails": [
    "[email protected]"
  ],
  "bcc_emails": [
    "[email protected]"
  ],
  "billing": {
    "email": "<string>",
    "phone": "<string>",
    "phone_code": "<string>",
    "iso_code": "<string>",
    "country": "<string>",
    "address_1": "<string>",
    "address_2": "<string>",
    "postal_code": "<string>",
    "district": "<string>",
    "state": "<string>",
    "province": "<string>",
    "tax_id": "<string>"
  }
}
'
{
  "success": true,
  "message": "Contact created successfully",
  "data": {
    "id": "64b8f1a2e4b0c8d9f0123456",
    "created_at": 1640995200,
    "updated_at": 1640995200,
    "type": "customer",
    "status": "active",
    "full_name": "John Doe",
    "email": "[email protected]",
    "description": "Primary contact for the company",
    "cc_emails": [
      "[email protected]",
      "[email protected]"
    ],
    "bcc_emails": [
      "[email protected]",
      "[email protected]"
    ],
    "billing": {
      "email": "[email protected]",
      "phone": "1234567890",
      "phone_code": "+1",
      "iso_code": "US",
      "country": "United States",
      "address_1": "123 Main Street",
      "address_2": "Suite 100",
      "postal_code": "12345",
      "district": "Downtown",
      "state": "CA",
      "province": "California",
      "tax_id": "12-3456789"
    }
  }
}

​
Create Contact

This endpoint allows you to create a new contact (customer or vendor) for a company in the accounting system.

​
Headers

ParameterTypeDescription
X-API-KEYstringFormation API Key (required)
Content-Typestringapplication/json

​
Request Body

{
  "type": "customer",
  "status": "active",
  "full_name": "John Doe",
  "email": "[email protected]",
  "description": "Primary customer contact",
  "cc_emails": ["[email protected]"],
  "bcc_emails": ["[email protected]"],
  "billing": {
    "email": "[email protected]",
    "phone": "+1234567890",
    "phone_code": "+1",
    "iso_code": "US",
    "country": "United States",
    "address_1": "123 Main St",
    "address_2": "Suite 100",
    "postal_code": "12345",
    "district": "Downtown",
    "state": "CA",
    "province": "California",
    "tax_id": "12-3456789"
  },
  "company_id": "64b8f1a2e4b0c8d9f0123456"
}

​
Required Fields

FieldTypeDescription
typestringContact type: “customer” or “vendor”
full_namestringFull name of the contact
emailstringEmail address of the contact
company_idstringID of the company this contact belongs to

​
Optional Fields

FieldTypeDescription
statusstringContact status
descriptionstringDescription or notes about the contact
cc_emailsarrayArray of CC email addresses
bcc_emailsarrayArray of BCC email addresses
billingobjectBilling information for the contact

​
Billing Object Fields

FieldTypeDescription
emailstringBilling email address
phonestringPhone number
phone_codestringPhone country code
iso_codestringCountry ISO code
countrystringCountry name
address_1stringAddress line 1
address_2stringAddress line 2
postal_codestringPostal code
districtstringDistrict
statestringState
provincestringProvince
tax_idstringTax identification number

​
Response

{
  "success": true,
  "message": "Contact created successfully",
  "data": {
    "id": "64b8f1a2e4b0c8d9f0123456",
    "created_at": 1686787200,
    "updated_at": 1686787200,
    "type": "customer",
    "status": "active",
    "full_name": "John Doe",
    "email": "[email protected]",
    "description": "Primary customer contact",
    "cc_emails": ["[email protected]"],
    "bcc_emails": ["[email protected]"],
    "billing": {
      "email": "[email protected]",
      "phone": "+1234567890",
      "phone_code": "+1",
      "iso_code": "US",
      "country": "United States",
      "address_1": "123 Main St",
      "address_2": "Suite 100",
      "postal_code": "12345",
      "district": "Downtown",
      "state": "CA",
      "province": "California",
      "tax_id": "12-3456789"
    }
  }
}

​
Response Parameters

ParameterTypeDescription
successbooleanIndicates if the operation was successful
messagestringAdditional information about the operation
dataobjectResponse data for successful requests
data.idstringUnique identifier for the created contact
data.created_atintegerCreation timestamp
data.updated_atintegerLast update timestamp
data.typestringContact type (“customer” or “vendor”)
data.statusstringContact status
data.full_namestringFull name of the contact
data.emailstringEmail address
data.descriptionstringContact description
data.cc_emailsarrayCC email addresses
data.bcc_emailsarrayBCC email addresses
data.billingobjectBilling information

​
Error Responses

​
Invalid Request (400)

{
  "success": false,
  "message": "Invalid request data",
  "error": {
    "code": "VALIDATION_FAILED",
    "details": "Field 'email' is required"
  }
}

​
Unauthorized (401)

{
  "success": false,
  "message": "API key is required",
  "error": {
    "code": "API_KEY_REQUIRED"
  }
}

​
Company Not Found (404)

{
  "success": false,
  "message": "Company not found",
  "error": {
    "code": "COMPANY_NOT_FOUND"
  }
}

​
Internal Server Error (500)

{
  "success": false,
  "message": "Internal server error",
  "error": {
    "code": "INTERNAL_ERROR"
  }
}

Authorizations

​
X-API-Key
string
header
required

Formation API key for authentication.

Body

application/json
​
type
enum<string>
required

Contact type

Available options:
customer,
vendor
​
full_name
string
required

Full name of the contact

​
email
string<email>
required

Email address

​
company_id
string
required

Company ID

​
status
string

Contact status

​
description
string

Contact description

​
cc_emails
string<email>[]

CC email addresses

​
bcc_emails
string<email>[]

BCC email addresses

​
billing
object

Response

Contact created successfully

​
success
boolean
Example:

true

​
message
string
Example:

"Contact created successfully"

​
data
object
Example:
{
  "id": "64b8f1a2e4b0c8d9f0123456",
  "created_at": 1640995200,
  "updated_at": 1640995200,
  "type": "customer",
  "status": "active",
  "full_name": "John Doe",
  "email": "[email protected]",
  "description": "Primary contact for the company",
  "cc_emails": ["[email protected]", "[email protected]"],
  "bcc_emails": ["[email protected]", "[email protected]"],
  "billing": {
    "email": "[email protected]",
    "phone": "1234567890",
    "phone_code": "+1",
    "iso_code": "US",
    "country": "United States",
    "address_1": "123 Main Street",
    "address_2": "Suite 100",
    "postal_code": "12345",
    "district": "Downtown",
    "state": "CA",
    "province": "California",
    "tax_id": "12-3456789"
  }
}