---
title: "Create a contact"
method: POST
path: "/organizations/{id_organization}/contacts"
tags: ["contacts"]
---

# Create a contact

`POST /organizations/{id_organization}/contacts`

## Request

- Base URL: `https://api.planvortex.com/v1.0.0`
- URL: `https://api.planvortex.com/v1.0.0/organizations/{id_organization}/contacts`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (client credentials, token URL `https://api.planvortex.com/v1.0.0/oauth/token`)

Creates a contact by hand, which is how you bring people in from your own system.

**Creating a contact does not let you write to them.** To send the first message the network has to allow it: WhatsApp needs an approved template, and Meta only allows an answer inside 24 hours of the contact writing first. What `social_identifiers` gives you is the link, not the permission.

## Path parameters

- `id_organization` string, required

## Request body

- ContactsContactCreate: A new contact. **At least one identifier is mandatory** (`ERROR_CODE_1601` otherwise): a contact with no channel is a contact nobody can write to. Creating is idempotent on the FIRST identifier: if the organization already has a contact with that channel and that `external_identifier`, you get the existing one back untouched — `name`, `profile_image` and `extra_data` of the request are ignored. There is no "already exists" error.
  - `name` string
  - `profile_image` string
  - `social_identifiers` ContactsSocialIdentifierInput[], required
    - `_id` string: Only when you are keeping an identifier the API already gave you.
    - `external_identifier` string: The contact id on that channel — the phone number on WhatsApp, the PSID on Messenger. Optional in the model, but a contact without it cannot be written to, and it is what deduplicates on create.
    - `social_network` 'facebook' | 'instagram' | 'linkedin' | 'tiktok' | 'twitter' | 'whatsapp' | 'youtube' | 'google_business' | 'bluesky' | 'discord' | 'email', required: Where a contact can be reached. Every social network that has messaging, plus `email` for a contact created by hand instead of arriving from a network. **This list grows** with the networks: treat it as an open enumeration.
  - `extra_data` ContactExtraData: Your own fields on the contact. The address block is known to PlanVortex; the six generic properties are yours to use, and they are what `extra_data` filters on.
    - `place_id` string
    - `address` string
    - `city` string
    - `state` string
    - `country` string
    - `country_code` string
    - `zip_code` union
      - string
      - number
    - `number` union
      - string
      - number
    - `building` union
      - string
      - number
    - `floor` union
      - string
      - number
    - `door` union
      - string
      - number
    - `coords` number[]: Longitude and latitude, in that order.
    - `string_property` string
    - `string_property2` string
    - `boolean_property` boolean
    - `boolean_property2` boolean
    - `number_property` number
    - `number_property2` number

## Response `200`

The created contact

- object
  - `contact` Contact, required: A person the organization exchanges messages with. The same contact can be reachable on several channels — that is what `social_identifiers` is.
    - `_id` string, required
    - `id_organization` string, required
    - `name` string
    - `profile_image` string: URL of the contact's avatar on the network. It belongs to the network and it can stop working.
    - `social_identifiers` SocialIdentifier[], required
      - `_id` string, required
      - `external_identifier` string: Identifier of the contact on that channel.
      - `social_network` 'facebook' | 'instagram' | 'linkedin' | 'tiktok' | 'twitter' | 'whatsapp' | 'youtube' | 'google_business' | 'bluesky' | 'discord' | 'email', required: Where a contact can be reached. Every social network that has messaging, plus `email` for a contact created by hand instead of arriving from a network. **This list grows** with the networks: treat it as an open enumeration.
      - `last_send_date` string, date-time: Last message received from the contact. On WhatsApp it is what opens the 24-hour window in which a free-form message is allowed.
    - `extra_data` ContactExtraData: Your own fields on the contact. The address block is known to PlanVortex; the six generic properties are yours to use, and they are what `extra_data` filters on.
      - `place_id` string
      - `address` string
      - `city` string
      - `state` string
      - `country` string
      - `country_code` string
      - `zip_code` union
        - string
        - number
      - `number` union
        - string
        - number
      - `building` union
        - string
        - number
      - `floor` union
        - string
        - number
      - `door` union
        - string
        - number
      - `coords` number[]: Longitude and latitude, in that order.
      - `string_property` string
      - `string_property2` string
      - `boolean_property` boolean
      - `boolean_property2` boolean
      - `number_property` number
      - `number_property2` number
    - `creator_keycloak_identifier` string: The user who created the contact, when it was created from the panel instead of arriving from a network.
    - `creation_date` string, date-time, required
    - `last_contact_update` string, date-time, required: Last time the contact's profile was refreshed from the network.

## Other responses

- `400`: Error. Classify by `code` in the body, never by the HTTP status.

---

[API](https://skmtc.dev/planvortex/apis/planvortex-api.md) · [All operations](https://skmtc.dev/planvortex/apis/planvortex-api/llms.txt) · [OpenAPI document](https://skmtc.dev/planvortex/apis/planvortex-api/revisions/abedbbc1cd52?raw)