Before You Begin

The Contacts API requires an API key to authenticate your request.

Header	Required	Description	Example
`api-key`	Yes	Your Netcore API key used to authenticate the request.	`YOUR_API_KEY`
`Content-Type`	Yes	Specifies that the request body is sent in JSON format.	`application/json`

Create Contacts

Use the Create Contacts API when you want to add one or more contacts to Netcore. You can create identified or anonymous contacts, add additional attributes, and assign contacts to audiences.

curl --location '{{BASE_URL}}/v5/contact/create' \
--header 'api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "data": {
    "contact_type": "identified",
    "contacts": [
      {
        "identity": "[email protected]",
        "email": "[email protected]"
      }
    ]
  }
}'

📘
Important: Replace YOUR_API_KEY with your actual API key.

Create Single Identified Contact

When to use: Use this when you want to add one new contact with their basic contact information.
What changes: Set contact_type to identified and provide the required identity.
Best for: Customer registration, signup, or adding an individual customer.

{
  "data": {
    "contact_type": "identified",
    "contacts": [
      {
        "identity": "[email protected]",
        "email": "[email protected]",
        "mobile": "919000000001"
      }
    ]
  }
}

Create Multiple Contacts

When to use: Use this when you need to create multiple contacts in a single request.

What changes: Add multiple contact objects inside the contacts array.

Limit: You can include up to 1,000 contacts per request.

Best for: Bulk creation or synchronizing new customers from another system such as a CRM.

{
  "data": {
    "contact_type": "identified",
    "contacts": [
      {
        "identity": "[email protected]",
        "email": "[email protected]"
      },
      {
        "identity": "[email protected]",
        "email": "[email protected]"
      }
    ]
  }
}

Create Contact with Additional Attributes

When to use: Use this when you want to store additional information about a contact along with their basic contact details.
What changes: Add an attributes object inside the contact.
Best for: Storing information such as name, location, customer type, or other contact attributes.

{
  "data": {
    "contact_type": "identified",
    "contacts": [
      {
        "identity": "[email protected]",
        "email": "[email protected]",
        "attributes": {
          "FIRST_NAME": "John",
          "STATE": "Maharashtra",
          "CUSTOMER_TYPE": "Premium"
        }
      }
    ]
  }
}

Create Contact and Assign it to Audience

When to use: Use this when you want to create a contact and associate them with one or more audiences in the same request.
What changes: Add audience_details inside the contact.
Best for: Adding a newly created customer directly to the audience(s) they belong to.

{
  "data": {
    "contact_type": "identified",
    "contacts": [
      {
        "identity": "[email protected]",
        "email": "[email protected]",
        "audience_details": [
          {
            "audience_id": [101, 102],
            "audience_type": "list"
          }
        ]
      }
    ]
  }
}

Create an anonymous contact

When to use: Use this when the contact does not yet have a known primary identity in Netcore.
What changes: Set contact_type to anonymous and provide the identifier(s) supported for anonymous contacts.
Best for: Contacts or visitors whose primary identity is not yet available.

{
  "data": {
    "contact_type": "anonymous",
    "contacts": [
      {
        "email": "[email protected]",
        "mobile": "919000000003"
      }
    ]
  }
}

Search Contact

Use the below sample use case to find identified contacts that belong to list 15, return their email, mobile number, and city, show 10 contacts at a time, and show the newest contacts first.

{
  "filtering_criteria_operator": "or",
  "filtering_criteria": [
    {
      "condition_operator": "and",
      "condition_details": [
        {
          "field": "contact_type",
          "field_category": "config",
          "operation": "equals",
          "value": [
            "identified"
          ]
        },
        {
          "field": "list_id",
          "field_category": "audience",
          "operation": "equals",
          "value": [
            15
          ]
        }
      ]
    }
  ],
  "output": {
    "get_count": false,
    "sorting": [
      {
        "field": "created_at",
        "direction": "desc"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10
    },
    "fields": [
      "EMAIL",
      "MOBILE",
      "CITY"
    ]
  }
}