> ## Documentation Index > Fetch the complete documentation index at: https://docs.jobin.cloud/llms.txt > Use this file to discover all available pages before exploring further. # Import contacts in bulk > Import up to 50 contacts and review the result for each person. Send 1–50 contacts in one request. Review each result and save the returned contact identifiers. If the request is interrupted, check whether the contacts were imported before sending it again. *Rate limit: 30 requests/minute per endpoint and workgroup. [Details](/development#rate-limits).* ## OpenAPI ````yaml openapi/jobin-integration.json POST /contacts/import/bulk openapi: 3.1.0 info: title: Jobin Integration API version: 1.0.0 description: >- Work with Jobin contacts and outreach sequences from your recruiting tools and AI assistants. See [integration guidelines](https://docs.jobin.cloud/development#rate-limits) for rate limits and retries. servers: - url: https://my.jobin.cloud/api/openapi/v1 description: Public OpenAPI base URL. Append each path below to this base URL. security: [] paths: /contacts/import/bulk: post: summary: Bulk import contacts description: >- Import 1–50 contacts with notes and tags. Review each result and save the returned contact identifiers before retrying an interrupted request. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ContactBulkImportRequest' responses: '201': description: Imported contact identifiers and the import options used. content: application/json: schema: $ref: '#/components/schemas/ContactBulkImportResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/RateLimitExceeded' '500': $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/ApiError' security: - ApiKeyAuth: [] components: schemas: ContactBulkImportRequest: type: object additionalProperties: false required: - contacts properties: contacts: type: array description: >- One to fifty contact import requests. Each item follows POST /contacts/import semantics so dedupe, notes, tags, overwrite mode, and optional auto-update stay consistent. minItems: 1 maxItems: 50 items: $ref: '#/components/schemas/ContactImportRequest' ContactBulkImportResponse: type: object properties: items: type: array items: $ref: '#/components/schemas/ContactImportResponse' count: type: integer description: Number of contacts imported or deduplicated by the request. ContactImportRequest: type: object additionalProperties: false required: - contact properties: contact: $ref: '#/components/schemas/ContactImportContactInput' notes: type: array maxItems: 25 items: type: string minLength: 1 maxLength: 4000 description: Trimmed, nonempty note. autoUpdate: type: boolean description: >- When true, the existing import path schedules automatic enrichment/update behavior for the contact. overwriteMode: type: string default: askBeforeOverwriting enum: - overwriteWithNewest - alwaysKeepOriginalOnOverwrite - askBeforeOverwriting description: Duplicate-handling mode used by the existing import service. ContactImportResponse: type: object properties: contactId: type: string autoUpdate: type: boolean overwriteMode: type: string enum: - overwriteWithNewest - alwaysKeepOriginalOnOverwrite - askBeforeOverwriting Error: type: object required: - code - error properties: code: type: string description: Stable error code. Input validation uses VALIDATION_ERROR. error: type: string description: >- User-facing message. Unknown failures return a generic message without internal details. example: code: UNHANDLED_EXCEPTION error: Unexpected error RateLimitError: type: object description: Returned when a public OpenAPI rate limit is exceeded. properties: statusCode: type: integer example: 429 error: type: string example: Too Many Requests message: type: string description: Human-readable description of the limit that was exceeded. retryAfterSeconds: type: integer description: Seconds to wait before retrying the request. ContactImportContactInput: type: object description: >- Contact fields accepted by POST /contacts/import. Additional JSON properties are accepted and passed into the existing contact import path for supported Jobin contact fields. properties: _id: type: string pattern: ^[a-fA-F0-9]{24}$ description: >- Optional existing contact id when the integration already knows the Jobin identifier. firstName: type: string minLength: 1 maxLength: 256 middleName: type: string minLength: 1 maxLength: 256 lastName: type: string minLength: 1 maxLength: 256 socialUrl: type: string format: uri maxLength: 2048 email: type: string format: email maxLength: 320 description: >- Work email address. Jobin uses workEmail when both fields are supplied. workEmail: type: string format: email maxLength: 320 privateEmail: type: string format: email maxLength: 320 otherEmails: type: array maxItems: 25 items: type: string format: email maxLength: 320 workPhone: type: string minLength: 1 maxLength: 256 description: Primary work landline phone number. privatePhone: type: string minLength: 1 maxLength: 256 description: Primary private landline phone number. otherPhones: type: array maxItems: 25 items: type: string minLength: 1 maxLength: 256 description: Additional landline phone numbers. workMobilePhone: type: string minLength: 1 maxLength: 256 description: Primary work mobile phone number. privateMobilePhone: type: string minLength: 1 maxLength: 256 description: Primary private mobile phone number. otherMobilePhones: type: array maxItems: 25 items: type: string minLength: 1 maxLength: 256 description: Additional mobile phone numbers. summary: type: string minLength: 1 maxLength: 4000 description: ' Trimmed, nonempty text; maximum 4000 characters.' tags: type: array maxItems: 50 items: $ref: '#/components/schemas/ContactImportTagInput' customFieldList: type: array maxItems: 100 description: >- Custom-field values identified by fieldName or customFieldDefinitionId. items: $ref: '#/components/schemas/ContactImportCustomFieldInput' additionalProperties: true ContactImportTagInput: oneOf: - type: string minLength: 1 maxLength: 256 description: Tag name. - type: object additionalProperties: false properties: value: type: string minLength: 1 maxLength: 256 iconName: type: string minLength: 1 maxLength: 256 color: type: string minLength: 1 maxLength: 256 required: - value ContactImportCustomFieldInput: type: object additionalProperties: false description: >- Custom-field value for contact import. Identify a free-text field with fieldName or use customFieldDefinitionId for a defined field. anyOf: - required: - fieldName - required: - customFieldDefinitionId properties: _id: type: string pattern: ^[a-fA-F0-9]{24}$ description: Existing embedded custom-field value identifier when present. fieldName: type: string minLength: 1 maxLength: 256 description: Canonical field name for a free-text custom field. value: type: string minLength: 1 maxLength: 4000 description: Text representation of the custom-field value. customFieldDefinitionId: type: string pattern: ^[a-fA-F0-9]{24}$ description: Workgroup custom-field definition identifier for a typed field. valueType: type: string enum: - freeText - number - date - list - range description: >- Optional client-side type metadata; Jobin resolves the authoritative type from the workgroup definition. textValue: type: string maxLength: 4000 minLength: 1 numberValue: type: number dateValue: type: string format: date-time listValue: type: string maxLength: 4000 minLength: 1 rangeValue: type: object additionalProperties: false required: - min - max properties: min: type: number max: type: number step: type: number unit: type: string minLength: 1 maxLength: 256 responses: BadRequest: description: Invalid request or expected business-rule failure. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: >- Missing or invalid authentication, or missing required authentication context. content: application/json: schema: $ref: '#/components/schemas/Error' RateLimitExceeded: description: >- Rate limit exceeded. Wait for the retry-after header before sending the next request. headers: retry-after: description: Seconds to wait before retrying. schema: type: integer x-ratelimit-limit: description: Maximum requests allowed in the current window. schema: type: integer x-ratelimit-remaining: description: Requests remaining in the current window. schema: type: integer x-ratelimit-reset: description: Seconds until the current window resets. schema: type: integer content: application/json: schema: oneOf: - $ref: '#/components/schemas/RateLimitError' - $ref: '#/components/schemas/Error' InternalServerError: description: Unexpected server failure. Internal details are masked. content: application/json: schema: $ref: '#/components/schemas/Error' ApiError: description: Other client or server failure. Unknown errors expose a generic message. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Primary public authentication method. Create keys in Jobin.cloud under Workgroups > Integrations > Custom integration. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.