---
title: "Upsert Contacts [Async]"
method: POST
path: "/contact/upsert"
tags: ["Contacts"]
---

# Upsert Contacts \[Async\]

`POST /contact/upsert`

## Request

- Base URL: `https://netcoreapi-main-prod-us.netcorein.com/v5`
- URL: `https://netcoreapi-main-prod-us.netcorein.com/v5/contact/upsert`
- Auth: API key in header `api-key`

The **Upsert Contact API** enables clients to update or create/insert (upsert) one or more contacts within a single request.

## Headers

- `api-key` string, required
- `Content-Type` string, required

## Request body

- object
  - `data` object, required
    - `contact_type` 'identified' | 'anonymous', required: Specify the type of contact to be created. Choose between `"identified"` or `"anonymous"`.
    - `contacts` object[], required: An array of contacts to create or update in a single request. For each contact, the API checks whether it already exists and creates or updates it accordingly.
      - `identity` string: - **Required** when `contact_type = "identified"` (identity serves as the primary key and can be `email`, `mobile`, or `custom parameter`). - **Not required** when `contact_type = "anonymous"`. **Validation:** Identity must match the format of the selected primary key: #### If identity = email - **Minimum length:** 1 character - **Maximum length:** 255 characters - **Pattern:** `^([a-z0-9_Xx])([a-z0-9+-Xx]+)(.[a-z0-9+-Xx]+)@([a-z0-9-]+.)+[a-z]{2,25}$` #### If identity = mobile - **Minimum length:** 7 character - **Maximum length:** 15 characters - **Pattern:** `^[0-9]{7,15}$`
      - `email` string: - **Required** when `contact_type = "identified"` **and the primary key is `email`**. - **Optional** when `contact_type = "identified"` **and the primary key is `mobile` or `custom parameter`**. - **Not required** when `contact_type = "anonymous"` **and the primary key is `email`** (anonymous contacts cannot use `email` as an identifier; only mobile is allowed).
      - `mobile` string: - **Required** when `contact_type = "identified"` **and the primary key is `mobile`**. - **Optional** when `contact_type = "identified"` **and the primary key is `email` or `custom parameter`**. - **Not required** when `contact_type = "anonymous"` **and the primary key is `mobile`** (anonymous contacts must use mobile as the identifier).
      - `attributes` object: - Specify attributes to be tagged to the contact as key–value pairs. - Keys represent attribute names, values represent attribute values (e.g., `"AGE": 30`). - All **system attributes** and **custom attributes** are allowed. - The request will be **rejected** if: - the attribute does not exist in the system, or - the attribute is a **derived attribute**.
        - `{{Atribute_Name}}` string
      - `audience_details` object[]: Used to assign audience groups to a specific contact. Each contact can have its own audience mapping.
        - `audience_id` integer[]: - **audience_id** – required when `audience_name` is not provided. - **Minimum length:** 1 - **Maximum length:** 2,147,483,647
        - `audience_name` string[]: - **audience_name** – required when `audience_id` is not provided. - **Minimum length:** 1 - **Maximum length:** 255 - **Pattern:** `^[a-zA-Z0-9 _&-]+$`
        - `audience_type` string: - **audience_type** (`string`) – allowed values: `list`, `ccg`. - For `contact_type = "anonymous"`, only `list` is allowed.
    - `audience_details` object[]: Used to assign audience groups to all contacts in the request. Audience mappings defined here apply globally to every contact.
      - `audience_id` integer[]: - **audience_id** – required when `audience_name` is not provided. - **Minimum length:** 1 - **Maximum length:** 2,147,483,647
      - `audience_name` string[]: - **audience_name** – required when `audience_id` is not provided. - **Minimum length:** 1 - **Maximum length:** 255 - **Pattern:** `^[a-zA-Z0-9 _&-]+$`
      - `audience_type` string: - **audience_type** (`string`) – allowed values: `list`, `ccg`. - For `contact_type = "anonymous"`, only `list` is allowed.

## Response `200`

Request accepted successfully. Contact processing continues asynchronously.

- object
  - `request_id` string, required: A unique identifier for the API request. Share this ID with the support team when reporting issues.
  - `code` 200 | 400 | 401 | 500, required: The response code, which mirrors the HTTP status code.
  - `status` 'success' | 'failed', required: Indicates the result reported by the API: `success` or `failed`.
  - `description` string, required: Api response description.

## Other responses

- `400`: Validation failure due to missing required fields, invalid data types, unsupported fields, or an incorrectly formatted request body.
- `401`: Unauthorized access due to a missing or invalid API key.
- `500`: An unexpected server error occurred while handling the request.

## Changes

- **2026-11-03** `6187aa20a923`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/netcorecloud/apis/contacts-api/changes/contact/upsert/post.md)

---

[API](https://skmtc.dev/netcorecloud/apis/contacts-api.md) - [All operations](https://skmtc.dev/netcorecloud/apis/contacts-api/llms.txt) - [OpenAPI document](https://skmtc.dev/netcorecloud/apis/contacts-api/revisions/6187aa20a923?raw)