### Create Contacts in Batch

Source: https://api-docs.omnisend.com/v5/docs/how-to-sync-contacts

Endpoint for creating multiple contacts simultaneously, improving efficiency and reducing API call overhead.

```APIDOC
## POST /batches

### Description
Creates multiple contacts in a single API call. Recommended for efficiency and scalability. The payload size should not exceed 1MB.

### Method
POST

### Endpoint
https://api.omnisend.com/v5/batches

### Parameters
#### Request Body
- **method** (string) - Required - The HTTP method for the batch operation (e.g., "POST").
- **endpoint** (string) - Required - The target endpoint for the batch operation (e.g., "contacts").
- **items** (array) - Required - A list of items to be processed in the batch.
  - **identifiers** (array) - Required - A list of identifiers for the contact.
    - **type** (string) - Required - The type of identifier (e.g., "email").
    - **id** (string) - Required - The identifier value.
    - **channels** (object) - Required - Channel-specific information.
      - **email** (object) - Required - Email channel details.
        - **status** (string) - Required - Subscription status (e.g., "subscribed").
        - **statusDate** (string) - Required - Date of status change (ISO 8601 format).
  - **firstName** (string) - Optional - The first name of the contact.
  - **lastName** (string) - Optional - The last name of the contact.
  - **country** (string) - Optional - The country of the contact.
  - **countryCode** (string) - Optional - The country code of the contact.
  - **city** (string) - Optional - The city of the contact.
  - **address** (string) - Optional - The address of the contact.
  - **postalCode** (string) - Optional - The postal code of the contact.
  - **gender** (string) - Optional - The gender of the contact.
  - **birthdate** (string) - Optional - The birthdate of the contact (YYYY-MM-DD format).

### Request Example
```json
{
    "method": "POST",
    "endpoint": "contacts",
    "items": [
        {
          "identifiers": [
            {
              "type":"email",
              "id": "vanessa.kensington@example.com",
              "channels": {
              "email": {
                "status": "subscribed",
                "statusDate": "2019-05-30T14:11:12Z"
                }
              }
            }
          ]
        },
        {
          "identifiers": [
          {
            "type":"email",
            "id": "vanessa@example.com",
            "channels": {
              "email": {
                "status": "subscribed",
                "statusDate": "2019-05-30T14:11:12Z"
                }
              }
            }
          ],

         "firstName":"Vanessa"
        }
    ]
}
```

### Response
#### Success Response (200)
- **batchId** (string) - The unique identifier for the batch operation.
- **status** (string) - The status of the batch operation (e.g., "processing").

#### Response Example
```json
{
  "batchId": "60a7b1e3c3e3e3a4b4b4b4b5",
  "status": "processing"
}
```
```

--------------------------------

### Recommended Events

Source: https://api-docs.omnisend.com/v5/reference/events-overview

Details on Omnisend's predefined recommended events, which are designed to work with pre-built automations and reporting. Examples include 'added product to cart', 'placed order', etc.

```APIDOC
## Recommended Events

Omnisend provides the following predefined recommended events:

*   added product to cart
*   started checkout
*   placed order
*   paid for order
*   ordered product
*   order refunded
*   order fulfilled
*   order canceled
*   viewed product

Each recommended event has a specific version and origin that must be used for accurate data tracking and automation.

Refer to specific event documentation or guides for correct origin and version details. For example:

*   How to: track cart events
*   How to: enable product abandonment
*   How to: enable cart/checkout abandonment
*   How to: send events using Events API
*   How to: enable order confirmation
```

--------------------------------

### Create Contact

Source: https://api-docs.omnisend.com/v5/docs/how-to-sync-contacts

Endpoint for creating a single contact in Omnisend. Ensures unique identifiers for each contact.

```APIDOC
## POST /contacts

### Description
Creates a new contact in Omnisend. If a contact with the same identifier already exists, the system may ignore the identifier or not create the contact if it's the only identifier.

### Method
POST

### Endpoint
https://api.omnisend.com/v5/contacts

### Parameters
#### Request Body
- **identifiers** (array) - Required - A list of identifiers for the contact.
  - **type** (string) - Required - The type of identifier (e.g., "email").
  - **id** (string) - Required - The identifier value.
  - **channels** (object) - Required - Channel-specific information.
    - **email** (object) - Required - Email channel details.
      - **status** (string) - Required - Subscription status (e.g., "subscribed").
      - **statusDate** (string) - Required - Date of status change (ISO 8601 format).
- **firstName** (string) - Optional - The first name of the contact.
- **lastName** (string) - Optional - The last name of the contact.
- **country** (string) - Optional - The country of the contact.
- **countryCode** (string) - Optional - The country code of the contact.
- **city** (string) - Optional - The city of the contact.
- **address** (string) - Optional - The address of the contact.
- **postalCode** (string) - Optional - The postal code of the contact.
- **gender** (string) - Optional - The gender of the contact.
- **birthdate** (string) - Optional - The birthdate of the contact (YYYY-MM-DD format).

### Request Example
```json
{
  "identifiers": [
    {
      "channels": {
        "email": {
          "status": "subscribed",
          "statusDate": "2020-02-29T10:07:28Z"
        }
      },
      "id": "jane.doe@example.com",
      "type": "email",
      "sendWelcomeMessage": true
    }
  ],
  "firstName": "Jane",
  "lastName": "Doe",
  "country": "United Kingdom",
  "countryCode": "GB",
  "city": "London",
  "address": "Westminster",
  "postalCode": "SW1A 1AA",
  "gender": "f",
  "birthdate": "1997-05-02"
}
```

### Response
#### Success Response (200)
- **contactId** (string) - The unique identifier for the created contact.

#### Response Example
```json
{
  "contactId": "60a7b1e3c3e3e3a4b4b4b4b4"
}
```
```

--------------------------------

### Make Authenticated API Request (HTTP)

Source: https://api-docs.omnisend.com/v5/reference/oauth

An example of an HTTP GET request to the Omnisend API v5, authenticated using a Bearer token. This demonstrates how to include the obtained access token in the Authorization header to access protected resources.

```HTTP
GET https://api.omnisend.com/v5/events
Content-Type: application/json
Authorization: Bearer RANDOMLY_GENERATED_ACCESS_TOKEN
```

--------------------------------

### Create Single Contact with cURL

Source: https://api-docs.omnisend.com/v5/docs/how-to-sync-contacts

Demonstrates how to create a single contact using the `POST /contacts` endpoint with a `curl` command. It requires authentication via an API key and specifies contact details in JSON format. Ensure unique identifiers are provided for each contact.

```shell
curl --request POST \
     --url https://api.omnisend.com/v5/contacts \
     --header 'X-API-KEY: MERCHANT_API_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data \
'{
  "identifiers": [
    {
      "channels": {
        "email": {
          "status": "subscribed",
          "statusDate": "2020-02-29T10:07:28Z"
        }
      },
      "id": "jane.doe@example.com",
      "type": "email",
      "sendWelcomeMessage": true
    }
  ],
  "firstName": "Jane",
  "lastName": "Doe",
  "country": "United Kingdom",
  "countryCode": "GB",
  "city": "London",
  "address": "Westminster",
  "postalCode": "SW1A 1AA",
  "gender": "f",
  "birthdate": "1997-05-02"
}'

```

--------------------------------

### Handle Authorization Callback (HTTP)

Source: https://api-docs.omnisend.com/v5/reference/oauth

Example of an HTTP callback URL after a user authorizes the application. The authorization code is provided as a query parameter, which your application must parse to proceed to the next step of exchanging it for an access token.

```HTTP
http://localhost:6000/?code=6O-KEB2KNCWKT7YVFYTF9G&state=adxcsasdcqws
```

--------------------------------

### Create Contacts in Batch with cURL

Source: https://api-docs.omnisend.com/v5/docs/how-to-sync-contacts

Illustrates how to create multiple contacts simultaneously using the `POST /batches` endpoint with `curl`. This method is efficient for bulk operations and helps manage API rate limits. The payload defines the operation (`POST`), target endpoint (`contacts`), and a list of items to be processed.

```shell
curl --request POST \
     --url https://api.omnisend.com/v5/batches \
     --header 'X-API-KEY: MERCHANT_API_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data \
'{
    "method": "POST",
    "endpoint": "contacts",
    "items": [
        {
          "identifiers": [
            {
              "type":"email",
              "id": "vanessa.kensington@example.com",
              "channels": {
              "email": {
                "status": "subscribed",
                "statusDate": "2019-05-30T14:11:12Z"
                }
              }
            }
          ]
        },
        {
          "identifiers": [
          {
            "type":"email",
            "id": "vanessa@example.com",
            "channels": {
              "email": {
                "status": "subscribed",
                "statusDate": "2019-05-30T14:11:12Z"
                }
              }
            }
          ],

         "firstName":"Vanessa"
        }
    ]
}'

```

--------------------------------

### Authenticate with API Key using cURL

Source: https://api-docs.omnisend.com/v5/reference/authentication

Demonstrates how to make an authenticated GET request to the Omnisend API v5 products endpoint using an API key. This requires setting the 'X-API-KEY' header with your valid API key.

```bash
curl --request GET \
  --url 'https://api.omnisend.com/v5/products' \
  --header 'X-API-KEY: AjWvksZpTG4JZBdc4'
```

--------------------------------

### Update Contact

Source: https://api-docs.omnisend.com/v5/docs/how-to-sync-contacts

Updates an existing contact using their unique ID. Note that two contacts cannot share the same identifier; attempting to update with an existing identifier will be ignored.

```APIDOC
## PATCH /contacts/{contactId}

### Description
Updates an existing contact identified by `contactId`. The system will ignore any provided identifier if it already exists for another contact.

### Method
PATCH

### Endpoint
/v5/contacts/{contactId}

#### Path Parameters
- **contactId** (string) - Required - The unique identifier of the contact to update.

#### Request Body
- **identifiers** (array[object]) - Required - A list of identifiers for the contact.
  - **channels** (object) - Required - Channel-specific information.
    - **email** (object) - Required - Email channel details.
      - **status** (string) - Required - Subscription status (e.g., "subscribed").
  - **id** (string) - Required - The identifier value (e.g., email address).
- **customProperties** (object) - Optional - A key-value map for custom contact properties.
  - **shoeSize** (integer) - Optional - Example custom property.
  - **eyesColor** (string) - Optional - Example custom property.
  - **maritalStatus** (string) - Optional - Example custom property.
- **city** (string) - Optional - The city associated with the contact.

### Request Example
```json
{
  "identifiers": [
    {
      "channels": {
        "email": {
          "status": "subscribed"
        }
      },
      "id": "jane.doe@example.com"
    }
  ],
  "customProperties": {
    "shoeSize": 42,
    "eyesColor": "blue",
    "maritalStatus": "single"
  },
  "city": "Los Angeles"
}
```

### Response
#### Success Response (200)
- **id** (string) - The updated contact's ID.
- **identifiers** (array[object]) - The updated list of identifiers.
- **customProperties** (object) - The updated custom properties.
- **city** (string) - The updated city.

#### Response Example
```json
{
  "id": "6321837c0b053d1f29598dad",
  "identifiers": [
    {
      "channels": {
        "email": {
          "status": "subscribed"
        }
      },
      "id": "jane.doe@example.com"
    }
  ],
  "customProperties": {
    "shoeSize": 42,
    "eyesColor": "blue",
    "maritalStatus": "single"
  },
  "city": "Los Angeles"
}
```
```

--------------------------------

### Generate OAuth Authorization Request (HTTP)

Source: https://api-docs.omnisend.com/v5/reference/oauth

Constructs the initial HTTP GET request to authorize an application. It includes parameters like client ID, redirect URI, response type, state, and scopes, which are necessary for the OAuth 2.0 Authorization Code Grant flow.

```HTTP
GET https://app.omnisend.com/oauth2/authorize?client_id=YOUR_CLIENT_ID
&redirect_uri=REDIRECT_URI
&response_type=code
&state=RANDOMLY_GENERATED_VALUE
&scope=RESOURCEX%20RESOURCEY
```

--------------------------------

### Update Contact with cURL

Source: https://api-docs.omnisend.com/v5/docs/how-to-sync-contacts

This snippet demonstrates how to update an existing contact using the `PATCH /contacts/{contactId}` endpoint with a `curl` command. It includes sample headers for authentication and content type, and a JSON payload specifying contact identifiers, custom properties, and city. Ensure you replace `MERCHANT_API_KEY` with your actual API key and `contactId` with the target contact's ID.

```shell
curl --request PATCH \
     --url https://api.omnisend.com/v5/contacts/6321837c0b053d1f29598dad \
     --header 'X-API-KEY: MERCHANT_API_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '\
{
  "identifiers": [
    {
      "channels": {
        "email": {
          "status": "subscribed"
        }
      },
      "id": "jane.doe@example.com"
    }
  ],
  "customProperties": {
    "shoeSize": 42,
    "eyesColor": "blue",
    "maritalStatus": "single"
  },
  "city": "Los Angeles"
}
'
```

--------------------------------

### Authentication - OAuth

Source: https://api-docs.omnisend.com/v5/reference/authentication

Information on using OAuth for authentication with the Omnisend API. Refer to the dedicated OAuth page for detailed instructions.

```APIDOC
## Authentication - OAuth

### Description
We also support OAuth. Please refer to the OAuth page for detailed integration instructions.

### Method
All HTTP Methods (GET, POST, PUT, DELETE, etc.)

### Endpoint
All Omnisend API v5 endpoints

### Parameters
Refer to the OAuth page for parameter details.

### Request Example
N/A (Refer to OAuth documentation)

### Response
N/A (Authentication is handled via OAuth flow)
```

--------------------------------

### Making a Request to the API

Source: https://api-docs.omnisend.com/v5/reference/oauth

Once you have obtained an access token, you can use it to make authenticated requests to Omnisend API endpoints.

```APIDOC
## Making Authenticated API Requests

Use the obtained access token in the `Authorization` header to authenticate your API requests.

### Request Example (GET /v5/events)
```http
GET https://api.omnisend.com/v5/events
Content-Type: application/json
Authorization: Bearer RANDOMLY_GENERATED_ACCESS_TOKEN
```
```

--------------------------------

### Authentication - API Key

Source: https://api-docs.omnisend.com/v5/reference/authentication

This section details how to authenticate API requests using an API key. You must include the 'X-API-KEY' header with your key in every request.

```APIDOC
## Authentication - API Key

### Description
Available authentication method - **API key**. You need to provide **X-API-KEY** header with every request.

### Method
All HTTP Methods (GET, POST, PUT, DELETE, etc.)

### Endpoint
All Omnisend API v5 endpoints

### Parameters
#### Headers
- **X-API-KEY** (string) - Required - Your Omnisend API key.

### Request Example
```bash
curl --request GET \
  --url 'https://api.omnisend.com/v5/products' \
  --header 'X-API-KEY: AjWvksZpTG4JZBdc4'
```

### Response
N/A (Authentication is handled via headers)
```

--------------------------------

### Custom Events

Source: https://api-docs.omnisend.com/v5/reference/events-overview

Information on creating and sending custom events to Omnisend for specific tracking needs not covered by recommended events. These offer flexibility in segmentation and automation triggers.

```APIDOC
## Custom Events

Custom events can be sent to Omnisend when the predefined recommended events do not cover specific requirements. These events are user-defined and offer flexibility for custom segmentation, automation triggers, and contact profile tracking.

For detailed instructions on sending custom events, refer to the 'How to: send custom events to trigger custom automations' guide.

When sending custom events, the `version` property can be omitted in the payload, and the `origin` property should be set appropriately (e.g., 'api' for custom store integrations).
```

--------------------------------

### Sending Events via REST API

Source: https://api-docs.omnisend.com/v5/reference/events-overview

This section covers how to send events to Omnisend using the REST API for server-side integrations. It outlines the structure of recommended and custom events, including the necessary 'version' and 'origin' properties.

```APIDOC
## POST /ecommerce/events

### Description
Sends an event to Omnisend. This endpoint can be used for both recommended and custom events.

### Method
POST

### Endpoint
/ecommerce/events

### Parameters
#### Request Body
- **type** (string) - Required - The type of the event (e.g., "product.viewed", "order.paid").
- **occurred_at** (integer) - Required - Unix timestamp of when the event occurred.
- **data** (object) - Required - The data associated with the event. The structure of this object depends on the event type.
  - **eventID** (string) - Optional - Unique identifier for the event to prevent duplicates. Works only for historical events.
  - **version** (string) - Required for recommended events, optional for custom events. The version of the event.
  - **origin** (string) - Required. The source of the event (e.g., 'api', 'app_name').

### Request Example
```json
{
  "type": "custom.my_event",
  "occurred_at": 1678886400,
  "data": {
    "eventID": "unique-event-id-123",
    "origin": "api",
    "custom_field": "custom_value"
  }
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the event was processed.

#### Response Example
```json
{
  "message": "Event processed successfully."
}
```
```

--------------------------------

### OAuth 2.0 Authorization Code Grant Flow

Source: https://api-docs.omnisend.com/v5/reference/oauth

This section details the three main steps involved in the OAuth 2.0 Authorization Code Grant flow for Omnisend API v5: generating an authorization request, accepting user authorization via callback, and exchanging the authorization code for an access token.

```APIDOC
## OAuth Authentication Flow

### Step 1: Generating an Auth Request

Initiate the OAuth flow by directing the user to the authorization endpoint with the following query parameters:

#### Query Parameters
- **response_type** (string) - Required - Must be `code` for the authorization code grant type.
- **client_id** (string) - Required - Your OAuth client ID.
- **redirect_uri** (string) - Required - The URL where the user will be redirected after authorization.
- **scopes** (string) - Required - The resources your app needs access to, separated by spaces.
- **state** (string) - Required - A randomly generated, unique value to maintain state.

#### Request Example (GET)
```http
GET https://app.omnisend.com/oauth2/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=REDIRECT_URI&response_type=code&state=RANDOMLY_GENERATED_VALUE&scope=RESOURCEX%20RESOURCEY
```

### Step 2: Accepting User Authorization (Callback)

After the user authorizes your application, they will be redirected to the `redirect_uri` specified in Step 1. The authorization code will be provided as a query parameter.

#### Request Example (Callback URL)
```http
http://localhost:6000/?code=6O-KEB2KNCWKT7YVFYTF9G&state=adxcsasdcqws
```

Extract the `code` from the query parameters to proceed to the next step.

### Step 3: Getting an Access Token

Exchange the received authorization `code` for an access token by making a POST request to the token endpoint.

#### Request Body Parameters
- **code** (string) - Required - The authorization code received in Step 2.
- **grant_type** (string) - Required - Must be `authorization_code`.
- **client_id** (string) - Required - Your OAuth client ID.
- **client_secret** (string) - Required - Your OAuth client secret.
- **redirect_uri** (string) - Required - The same redirect URI used in Step 1 and Step 2.

#### Request Example (POST)
```http
POST https://app.omnisend.com/oauth2/token
Content-Type: application/x-www-form-urlencoded

client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=authorization_code&code=AUTH_CODE&redirect_uri=REDIRECT_URI
```

#### Success Response (200)
```json
{
  "access_token": "RANDOMLY_GENERATED_ACCESS_TOKEN",
  "expires_in": 9223372036,
  "refresh_token": "RANDOMLY_GENERATED_REFRESH_TOKEN",
  "scope": "RESOURCEX RESOURCEY",
  "token_type": "Bearer"
}
```

This response provides the `access_token`, which is used for making authenticated API requests.
```

--------------------------------

### Exchange Authorization Code for Access Token (HTTP)

Source: https://api-docs.omnisend.com/v5/reference/oauth

Sends a POST request to exchange the authorization code obtained from the user callback for an access token. This request requires the client ID, client secret, grant type, authorization code, and redirect URI.

```HTTP
POST https://app.omnisend.com/oauth2/token
Content-Type: application/x-www-form-urlencoded

client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&grant_type=authorization_code
&code=AUTH_CODE
&redirect_uri=REDIRECT_URI
```

--------------------------------

### Receive Access Token Response (JSON)

Source: https://api-docs.omnisend.com/v5/reference/oauth

The JSON response received after successfully exchanging an authorization code for an access token. It contains the access token, its expiration time, refresh token, granted scopes, and token type.

```JSON
{
  "access_token": "RANDOMLY_GENERATED_ACCESS_TOKEN",
  "expires_in": 9223372036,
  "refresh_token": "RANDOMLY_GENERATED_REFRESH_TOKEN",
  "scope": "RESOURCEX RESOURCEY",
  "token_type": "Bearer"
}
```

--------------------------------

### Event Deduplication

Source: https://api-docs.omnisend.com/v5/reference/events-overview

Explanation of how to prevent duplicate event processing in Omnisend using the `eventID` and `eventTime` properties. Note that this feature is for historical events only.

```APIDOC
## Event Deduplication

To prevent duplicate event processing, use the `eventID` property in conjunction with `eventTime`. If an event with the same `eventID` and `eventTime` is submitted multiple times, Omnisend will process it only once.

**Note:** This deduplication mechanism works only for historical events and is not effective for real-time events used in automations.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.