> ## Documentation Index > Fetch the complete documentation index at: https://docs.subscriber.dev/llms.txt > Use this file to discover all available pages before exploring further. # Bulk create or update subscribers > Upserts up to 500 subscribers per request. Each row is matched to an existing subscriber by publicId, then externalId, then email (in that order); if none match, a new subscriber is created. Rows are processed independently, so one failing row does not fail the batch. ## OpenAPI ````yaml /openapi.json post /subscribers/bulk openapi: 3.1.0 info: title: subscriber.dev API description: >- Trigger workflows, manage subscribers and send broadcasts. Authenticate with an API key in the X-API-Key header: the key decides the environment. Docs: https://docs.subscriber.dev version: '1.0' contact: {} servers: - url: https://api.subscriber.dev description: Cloud security: [] tags: [] paths: /subscribers/bulk: post: tags: - Subscribers summary: Bulk create or update subscribers description: >- Upserts up to 500 subscribers per request. Each row is matched to an existing subscriber by publicId, then externalId, then email (in that order); if none match, a new subscriber is created. Rows are processed independently, so one failing row does not fail the batch. operationId: bulkUpsertSubscribers parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BulkUpsertSubscribersRequest' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/BulkUpsertSubscribersResponse' '401': description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Environment not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Rate limited. Wait a second and retry. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - bearer: [] - api-key: - subscribers:write components: schemas: BulkUpsertSubscribersRequest: type: object properties: subscribers: minItems: 1 maxItems: 500 type: array items: type: object properties: publicId: description: >- Bring your own identifier. Used (along with externalId and email) to find an existing subscriber to update; if none match, a new subscriber is created. type: string minLength: 1 maxLength: 255 email: type: string format: email pattern: >- ^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ phone: type: string externalId: type: string firstName: type: string lastName: type: string name: type: string attributes: type: object propertyNames: type: string additionalProperties: {} preferences: description: >- Omit entirely to leave existing preferences untouched on update. type: object properties: email: type: boolean required: - subscribers BulkUpsertSubscribersResponse: type: object properties: results: type: array items: type: object properties: index: type: number status: type: string enum: - created - updated - error subscriber: type: object properties: publicId: type: string email: type: - string - 'null' phone: type: - string - 'null' externalId: type: - string - 'null' firstName: type: - string - 'null' lastName: type: - string - 'null' name: type: - string - 'null' attributes: anyOf: - type: object propertyNames: type: string additionalProperties: {} - type: 'null' createdVia: description: >- How the subscriber was created: "api", "mcp", or an inbound source such as "stripe". type: - string - 'null' createdAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ updatedAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ unsubscribeUrl: type: - string - 'null' required: - publicId - email - phone - externalId - firstName - lastName - name - attributes - createdVia - createdAt - updatedAt - unsubscribeUrl preferences: type: object properties: publicId: type: string email: type: boolean version: type: number createdAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ required: - publicId - email - version - createdAt error: type: string required: - index - status summary: type: object properties: created: type: number updated: type: number errored: type: number required: - created - updated - errored required: - results - summary ErrorResponse: type: object properties: statusCode: type: integer example: 404 message: type: string example: Workflow not found error: type: string example: Not Found errors: description: Which fields failed validation, on a 400. type: array items: type: object properties: path: type: array items: anyOf: - type: string - type: number message: type: string code: type: string required: - path - message required: - statusCode - message securitySchemes: bearer: scheme: bearer type: http description: >- A session token from `subscriber login`, used by subscriber.dev's own apps. Requests about an environment also need its ID in the `x-environment-id` header. From your own code, use an API key. api-key: type: apiKey in: header name: X-API-Key description: An environment API key. Keep it on your server. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.