> ## Documentation Index > Fetch the complete documentation index at: https://docs.enginy.ai/llms.txt > Use this file to discover all available pages before exploring further. # Bulk create contacts > Create up to 100 contacts in a single request. Each item behaves exactly like `POST /v1/contact` (including nested/aliased company data, per-item `mergeWithExisting`, `listId`, and custom/AI fields). Items are processed independently: the request succeeds with a per-item `results` array and a `summary`, so one invalid contact does not roll back the rest. Responses include direct Enginy app URLs when available. Each successful result includes `appUrl` for the contact and `companyAppUrl` when a company is associated. MCP agents should return those URLs to users whenever they are present in the response. > **Required scope:** `CONTACTS_WRITE` > > **Rate limit:** 30 requests per minute ## OpenAPI ````yaml https://openapi.enginy.ai/definitions.json post /v1/contacts/bulk openapi: 3.1.0 info: title: Enginy API version: 1.0.0 description: Public API for Enginy platform servers: - url: https://openapi.enginy.ai description: Configured server security: [] tags: - name: AI Variables description: >- Manage AI variables and discover the entity fields you can reference in prompts and entity requests. - name: Inbox description: >- Inbox endpoints for listing contact threads, reading thread messages, managing tags, and sending manual replies. - name: Workflows description: >- Build, validate, publish, run, and inspect advanced (graph) workflows, plus the block/condition catalog needed to author a workflow plan. paths: /v1/contacts/bulk: post: tags: - Contacts summary: Bulk create contacts description: >- Create up to 100 contacts in a single request. Each item behaves exactly like `POST /v1/contact` (including nested/aliased company data, per-item `mergeWithExisting`, `listId`, and custom/AI fields). Items are processed independently: the request succeeds with a per-item `results` array and a `summary`, so one invalid contact does not roll back the rest. Responses include direct Enginy app URLs when available. Each successful result includes `appUrl` for the contact and `companyAppUrl` when a company is associated. MCP agents should return those URLs to users whenever they are present in the response. > **Required scope:** `CONTACTS_WRITE` > > **Rate limit:** 30 requests per minute requestBody: content: application/json: schema: type: object properties: contacts: type: array items: type: object properties: firstName: type: string description: First name of the contact lastName: type: string description: Last name of the contact professionalEmail: type: string format: email description: Professional email address of the contact jobTitle: type: string description: Job title of the contact linkedInProfileUrl: type: string format: uri description: LinkedIn profile URL of the contact mobilePhone: type: string description: Mobile phone number of the contact phones: type: string description: Other phone numbers (comma-separated) linkedInHeadline: type: string description: LinkedIn headline contactCountry: type: string description: Country of the contact company: type: object properties: name: type: string description: Company name domain: type: string description: Company website domain companyLinkedInUrl: type: string format: uri description: Company LinkedIn URL industry: type: string description: Industry sector website: type: string format: uri description: Company website URL additionalProperties: {} description: Company information to associate with the contact companyName: type: string description: >- Alias for `company.name` when creating or matching the associated company companyDomain: type: string description: >- Alias for `company.domain` when creating or matching the associated company companyLinkedInUrl: type: string format: uri description: >- Alias for `company.companyLinkedInUrl` when creating or matching the associated company companyIndustry: type: string description: Alias for `company.industry` companyWebsite: type: string format: uri description: Alias for `company.website` listId: type: integer exclusiveMinimum: 0 description: ID of the list to add the contact to mergeWithExisting: type: boolean default: true description: >- Whether to merge with an existing contact or company. Contact matches use normalized LinkedIn profile URL, or exact first name + last name + company name. Company matches use normalized LinkedIn URL, domain, website, or exact name. Defaults to true. additionalProperties: {} minItems: 1 maxItems: 100 description: >- Contacts to create in a single request (1-100). Each item accepts the same fields as `POST /v1/contact`, including nested/aliased company data, per-item `listId`, `mergeWithExisting`, and custom/AI fields by name. required: - contacts examples: basic: summary: Create two contacts, each with company data value: contacts: - firstName: Ada lastName: Lovelace company: name: Analytical Engines domain: analytical-engines.com - firstName: Alan lastName: Turing companyName: Bletchley mergeWithExisting: true listId: 123 responses: '200': description: >- Batch processed. Each contact has an entry in `data.results` (in request order); inspect `success` and `summary` for partial failures. content: application/json: schema: type: object properties: status: type: string enum: - success message: type: string data: type: object properties: results: type: array items: type: object properties: index: type: integer description: >- Zero-based position of this contact in the request array. success: type: boolean description: >- Whether this contact was created or merged successfully. contact: type: object properties: id: type: number description: ID of the created or updated contact appUrl: type: string format: uri description: >- Direct Enginy app URL for opening the contact. firstName: type: - string - 'null' description: First name of the contact lastName: type: - string - 'null' description: Last name of the contact professionalEmail: type: - string - 'null' description: Professional email address linkedinProfileUrl: type: - string - 'null' description: LinkedIn profile URL companyId: type: - number - 'null' description: ID of the associated company companyAppUrl: type: - string - 'null' format: uri description: >- Direct Enginy app URL for opening the associated company, when available. createdAt: type: string format: date-time description: Date and time when the contact was created contactOutcome: type: string enum: - CREATED - MERGED_UPDATED - MERGED_NOOP description: >- Whether the contact was newly created or merged contactMatchedBy: type: string enum: - LINKEDIN_URL - NAME_COMPANY description: >- How an existing contact was matched when mergeWithExisting reused a record companyOutcome: type: string enum: - NONE - CREATED - MERGED_UPDATED - MERGED_NOOP description: >- Whether the associated company was created, merged, or left unchanged companyMatchedBy: type: string enum: - LINKEDIN_URL - DOMAIN - WEBSITE - NAME description: >- How an existing company was matched when mergeWithExisting reused a record warnings: type: array items: type: string description: >- Non-fatal warnings describing merge or no-op behavior required: - id - appUrl - firstName - lastName - professionalEmail - linkedinProfileUrl - companyId - companyAppUrl - createdAt - contactOutcome - companyOutcome - warnings description: >- The created or merged contact. Present only when `success` is true. error: type: object properties: message: type: string description: Human-readable reason this contact failed. details: type: object additionalProperties: {} description: >- Structured, machine-actionable error context when available. required: - message description: >- Failure detail. Present only when `success` is false. required: - index - success description: >- Per-item outcomes in the same order as the submitted `contacts` array. summary: type: object properties: total: type: integer description: Number of contacts submitted. created: type: integer description: Number of contacts newly created. merged: type: integer description: Number of contacts merged into an existing record. failed: type: integer description: >- Number of contacts that could not be created or merged. required: - total - created - merged - failed description: Aggregate counts for the batch. required: - results - summary required: - status - message - data '400': description: >- Bad request - the batch envelope failed validation (e.g. empty or too large) '500': description: Internal server error security: - apiKey: [] components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key ````