Skip to main content
POST
/
api
/
v1
/
contacts
/
create

​
Create Contact

Create a new contact with the specified information.

​
Endpoint

POST /api/v1/contacts/create

​
Authentication

This endpoint requires an API key with the can_read_contacts permission.

​
Request Body

ParameterTypeRequiredDescription
first_namestringYesFirst name of the contact
last_namestringNoLast name of the contact
emailstringNoEmail address of the contact
companystringNoCompany or organization name
websitestringNoCompany or personal website URL
addressstringNoStreet address
citystringNoCity
statestringNoState or province
zip_codestringNoPostal or ZIP code
countrystringNoCountry (default: “US”)
statusstringNoContact status (default: “not_contacted”)
stagestringNoContact stage (default: “lead”)
team_idintegerNoID of the team to assign the contact to
tagsarrayNoArray of tag names to associate with the contact
phone_numbersarrayNoArray of phone number objects
custom_contextobjectNoCustom fields and data
industry_contextobjectNoIndustry-specific information

​
Phone Number Object

ParameterTypeRequiredDescription
phone_numberstringYesPhone number in E.164 format
phone_typestringNoType of phone (mobile, work, home, etc.)
primarybooleanNoWhether this is the primary phone number
do_not_callbooleanNoWhether this number is on the do not call list

​
Example Request Body

{
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]",
  "company": "Acme Corp",
  "website": "https://acme.example.com",
  "address": "123 Main St",
  "city": "San Francisco",
  "state": "CA",
  "zip_code": "94105",
  "country": "US",
  "status": "not_contacted",
  "stage": "lead",
  "team_id": 101,
  "tags": ["New Lead", "Website Inquiry"],
  "phone_numbers": [
    {
      "phone_number": "+15551234567",
      "phone_type": "mobile",
      "primary": true,
      "do_not_call": false
    },
    {
      "phone_number": "+15552345678",
      "phone_type": "work",
      "primary": false,
      "do_not_call": false
    }
  ],
  "custom_context": {
    "lead_source": "Website",
    "budget": "$5,000-$10,000",
    "decision_maker": true
  },
  "industry_context": {
    "company_size": "50-250",
    "industry_vertical": "Technology"
  }
}

​
Response

{
  "id": 123,
  "first_name": "John",
  "last_name": "Doe",
  "full_name": "John Doe",
  "email": "[email protected]",
  "message": "Contact created successfully"
}

​
Error Codes

Status CodeError CodeDescription
400missing_first_nameFirst name is required
400invalid_jsonInvalid JSON payload
400validation_errorValidation error with details
401authentication_requiredNo API key was provided
401invalid_keyThe API key is invalid or inactive
403permission_deniedThe API key doesn’t have the required permission
403team_access_deniedYou do not have access to this team
404team_not_foundTeam not found
500server_errorAn unexpected server error occurred

​
Example Request

curl -X POST 'https://api.klen.ai/api/v1/contacts/create' \
  -H 'Authorization: Bearer klen_abcdef123456789' \
  -H 'Content-Type: application/json' \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "company": "Acme Corp",
    "phone_numbers": [
      {
        "phone_number": "+15551234567",
        "phone_type": "mobile",
        "primary": true
      }
    ],
    "tags": ["New Lead", "Website Inquiry"]
  }'

​
Example Response

{
  "id": 123,
  "first_name": "John",
  "last_name": "Doe",
  "full_name": "John Doe",
  "email": "[email protected]",
  "message": "Contact created successfully"
}

​
Notes

  • The newly created contact will be owned by the user associated with the API key.
  • If team_id is provided, the contact will be associated with that team, assuming the user has access to the team.
  • The first phone number in the phone_numbers array will be set as the primary one if no phone number has the primary flag set to true.
  • You can assign tags to the contact during creation. If a tag doesn’t exist, it will be created.
  • Custom context fields can be used to store additional information specific to your business needs.