Create a contact

POST/api/v2/contacts

Adds a contact. Returns 201 when created, or 200 when an existing contact is updated instead.

Existing contacts are matched on manychat_id, then instagram_id, then username. An active match returns 409, with one exception: an inbound contact created again with source: "outbound" gets the outreach details added and returns 200. An archived match is reactivated and returns 200.

Rate limit 150 requests per minute

Headers

x-api-keyheaderRequired
Your API key.
Content-TypeheaderRequired
application/json

Body

usernamestringRequired
Instagram username, with or without @, up to 30 characters.
sourcestringRequired
inbound (they messaged you first) or outbound (you reached out first). Decides whether you send conversation or outreach.
conversation.last_inbound_atstring
Required for inbound, not allowed for outbound. When they last messaged you, ISO 8601.
conversation.last_message_previewstring
Required for inbound, not allowed for outbound. Text of that message, up to 2,000 characters.
outreach.reasonstring
Required for outbound, not allowed for inbound. Why you reached out, up to 200 characters.
outreach.messagestring
Required for outbound, not allowed for inbound. The message you sent, up to 2,000 characters.
outreach.message_labelstring
Label for the outreach message, up to 200 characters.
full_namestring
Display name, up to 200 characters.
instagram_idstring
Instagram user id, up to 100 characters.
manychat_idstring
ManyChat subscriber id, up to 100 characters.
tagsarray
Tag names, up to 20 of 50 characters each. Missing tags are created.
tag_colorstring
Color for tags created by this request. Hex code (#2563eb) or color name (blue). Default gray.
notestring
Note to add, up to 1,000 characters.
created_bystring
Email of the team member who added the contact.
assigned_tostring
Email of the team member to assign it to.
activate_follow_upsboolean
Start follow-ups for this contact. Default true.

Errors

Error	When
400`missing_conversation`	Inbound contact without `conversation.last_inbound_at` and `conversation.last_message_preview`.
400`missing_outreach`	Outbound contact without `outreach.reason` and `outreach.message`.
400`invalid_conversationinvalid_outreach`	Outbound contact with `conversation` fields, or inbound contact with `outreach` fields.
400`invalid_<field>`	A field has a value that is not allowed or is too long, for example `invalid_username` or `invalid_tags`. `message` names it.
400`invalid_assigned_to`	`assigned_to` is not an email address or not a member of your organization.
400`invalid_created_by`	created_by is not a valid email address.
403`user_not_in_organization`	The created_by email belongs to someone outside your organization.
404`unknown_created_by`	No user with the created_by email.
403`subscription_cancelled`	Your subscription is cancelled.
409`contact_already_exists`	A contact with this username, Instagram id or ManyChat id already exists.

Request

curl -X POST "https://app.dmtracker.ai/api/v2/contacts" \
  -H "x-api-key: $DMTRACKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "jane.fitness",
    "source": "inbound",
    "full_name": "Jane Cooper",
    "conversation": {
      "last_inbound_at": "2026-10-21T15:12:47Z",
      "last_message_preview": "Hi! How much is the coaching program?"
    },
    "tags": [
      "hot lead"
    ]
  }'

Response 201

{
  "status": "success",
  "message": "Contact created successfully",
  "data": {
    "id": "7c1e9a52-3f4b-4d2a-9e61-0b8f2d5c4a17",
    "username": "jane.fitness",
    "full_name": "Jane Cooper",
    "source": "inbound",
    "status": "open",
    "pipeline_stage": {
      "id": "2b6f0e1a-8d3c-4f57-a1e9-5c7d9b3e0f42",
      "name": "New Lead",
      "color": "#3B82F6",
      "position": 1
    },
    "tags": [
      {
        "id": 287,
        "name": "hot lead",
        "color": "#22C55E"
      }
    ],
    "added_by": "api",
    "created_at": "2026-10-29T10:05:12.000+00:00"
  }
}

Shortened. data is the full contact object.