> ## Documentation Index
> Fetch the complete documentation index at: https://developer.notocat.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create or update in bulk

> Learn how to create or update contacts in bulk using the Notocat API. This guide covers the POST /contacts endpoint, allowing you to manage your subscriber data efficiently.

The endpoint can be used to create a full list of contacts with Notocat. If a contact already exists, the data will be merged. The contacts can be updated in bulk when provided with IDs or emails that already exist in the database. If the contact does not exist, it will be created with the email provided.

**The endpoint accepts a minimum of 1 contact and a maximum of 1000 contacts.**


## OpenAPI

````yaml POST /contacts
openapi: 3.0.1
info:
  title: OpenAPI Contacts
  description: The contacts API allows you to manage your contacts in Notocat.
  version: 1.0.0
servers:
  - url: https://api.notocat.com/v1
security:
  - bearerAuth: []
paths:
  /contacts:
    post:
      description: Creates or updates contacts in bulk
      requestBody:
        description: Contacts to add or update
        content:
          application/json:
            schema:
              type: object
              properties:
                newsletter_id:
                  type: string
                  description: The newsletter ID
                contacts:
                  type: array
                  items:
                    $ref: '#/components/schemas/NewContact'
                  minItems: 1
                  maxItems: 1000
                  description: An array of contacts to add or update
              required:
                - newsletter_id
                - contacts
        required: true
      responses:
        '200':
          description: Contact response
          content:
            application/json:
              schema:
                type: object
                properties:
                  synced:
                    type: integer
        '400':
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    NewContact:
      required:
        - email
      type: object
      properties:
        email:
          description: The email of the contact
          type: string
        name:
          description: The name of the contact
          type: string
        first_name:
          description: The first name of the contact
          type: string
        last_name:
          description: The last name of the contact
          type: string
        subscribed:
          description: Subscription status of the contact
          type: boolean
          default: true
        custom_fields:
          description: >-
            Custom fields for the contact. Can be a `key: value` object or an
            array of objects. If the value is a date, it must be in ISO format
            or YYYY-MM-DD to be picked up correctly.
          oneOf:
            - type: object
            - type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                    description: Name of the custom field
                  value:
                    type: string
                    description: Value of the custom field
                  type:
                    type: string
                    description: >-
                      The data type of the custom field. Can be `string`,
                      `number`, `date`. This data is useful when segmenting
                      contacts. If the value is a date, it must be in ISO format
                      or YYYY-MM-DD to be picked up correctly.
                required:
                  - name
                  - value
                  - type
    Error:
      required:
        - error
        - message
      type: object
      properties:
        error:
          type: integer
          format: int32
        message:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````