Before You Begin

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

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]"
      }
    ]
  }
}'

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 an Anonymous Contact

When to use: Use this when you want to create a contact that does not have a known primary identity.

What changes: Set contact_type to anonymous and provide the available contact information such as email or mobile.

Best for: Website visitors, users, or other contacts whose primary identity is not yet known.

Sample request

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

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"
      }
    ]
  }
}

Create Multiple Contacts with Different Attributes

When to use: Use this when you want to create multiple contacts and store different attribute values for each contact.

What changes: Add an attributes object to each contact.

Best for: Syncing customer data from a CRM, database, or other customer system.

{
  "data": {
    "contact_type": "identified",
    "contacts": [
      {
        "identity": "[email protected]",
        "email": "[email protected]",
        "attributes": {
          "FIRSTNAME": "John",
          "CUSTOMER_TYPE": "Premium",
          "CITY": "Mumbai"
        }
      },
      {
        "identity": "[email protected]",
        "email": "[email protected]",
        "attributes": {
          "FIRSTNAME": "Mary",
          "CUSTOMER_TYPE": "Standard",
          "CITY": "Goa"
        }
      }
    ]
  }
}

Create Contact with Attributes and Audience Assignment

When to use: Use this when you want to create a contact, store additional information, and assign the contact to an audience in the same request.

What changes: Add both attributes and contact-level audience_details.

Best for: Adding a newly registered customer directly to the appropriate audience.

{
  "data": {
    "contact_type": "identified",
    "contacts": [
      {
        "identity": "[email protected]",
        "email": "[email protected]",
        "attributes": {
          "FIRSTNAME": "John",
          "CUSTOMER_TYPE": "Premium"
        },
        "audience_details": [
          {
            "audience_id": [101],
            "audience_type": "list"
          }
        ]
      }
    ]
  }
}

Good to know: Contact-level audience_details applies only to that contact.

Create Multiple Contacts and Add All of Them to an Audience

When to use: Use this when all contacts in a request need to be added to the same audience.

What changes: Add audience_details at the data level instead of adding it to each contact.

Best for: Bulk onboarding or importing a group of customers into the same list.

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

Good to know: Request-level audience_details applies to all contacts in the request.

Create Contacts and Add Them to Multiple Audiences

When to use: Use this when newly created contacts should belong to more than one audience.

What changes: Provide multiple audience IDs in audience_id.

Best for: Assigning customers to multiple segments during onboarding.

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

Good to know: The audience_type determines whether the specified audiences are list or ccg.

Create Contact Using Audience Name

When to use: Use this when you know the audience name but do not have the audience ID.

What changes: Use audience_name instead of audience_id.

Best for: Integrations where audience names are maintained by the customer rather than audience IDs.

{
  "data": {
    "contact_type": "identified",
    "contacts": [
      {
        "identity": "[email protected]",
        "email": "[email protected]"
      }
    ],
    "audience_details": [
      {
        "audience_name": ["Newsletter Subscribers"],
        "audience_type": "list"
      }
    ]
  }
}

Create Contact with Contact-Level and Request-Level Audiences

When to use: Use this when all contacts should be added to a common audience, while specific contacts also need to be added to additional audiences.

What changes: Use data.audience_details for the common audience and contact-level audience_details for contact-specific audiences.

Best for: Complex onboarding or segmentation scenarios.

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

Create Anonymous Contact with Attributes

When to use: Use this when you want to create an anonymous contact and store additional information available at that point.

What changes: Set contact_type to anonymous and provide the supported anonymous contact information.

Best for: Visitors or users whose primary identified identity is not yet available.

{
  "data": {
    "contact_type": "anonymous",
    "contacts": [
      {
        "email": "[email protected]",
        "mobile": "919000000003",
        "attributes": {
          "CITY": "Mumbai",
          "SOURCE": "Website"
        }
      }
    ]
  }
}

Create Contacts with List and Control Group Audiences

When to use: Use this when contacts need to be assigned to both a regular list and a control group list.

What changes: Add separate audience_details entries with the appropriate audience_type.

Best for: Journey-related use cases where some contacts need to be part of a control group.

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

Good to know: list and ccg have different purposes. A list can be used for supported engagement activities, while a ccg is used for the control group feature within a journey.