---
updatedAt: 2026-08-27T12:37:17.000Z
agentTools:
projectIndex: https://developer.candis.io/llms.txt
---
# Create Contacts
Create creditor or debtor contacts
| Request limit | Record limit | Batch size |
| -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------- |
| 500 requests per minute per organization
2,500 per minute per holding | 600 records per minute per organization (burst 1,000)
900 per minute per holding (burst 1,500) | Maximum 100 records per request |
Both limits are evaluated on every request. A request is rejected when either is exceeded.
For requests containing the maximum of 100 records:
* Following an idle period, 10 consecutive requests are accepted without delay. This corresponds to the 1,000-record burst allowance.
* Sustained submission is subsequently paced at one request per 10 seconds, approximately 6 per minute.
* The allowance is restored to its ceiling after approximately 100 seconds without submissions.
[Rate Limiting Policy](/docs/rate-limiting-policy)
# OpenAPI definition
```json
{
"openapi": "3.0.0",
"paths": {
"/v1/organizations/{organizationId}/imports/contacts": {
"post": {
"description": "Create creditor or debtor contacts",
"operationId": "createContact",
"parameters": [
{
"name": "organizationId",
"required": true,
"in": "path",
"description": "The organization ID.",
"schema": {
"example": "alpha-organization",
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"oneOf": [
{
"title": "Debtor Contact",
"type": "object",
"properties": {
"accountReceivableNumber": {
"type": "string",
"description": "Account Receivable number",
"example": "S742932"
},
"name": {
"type": "string",
"description": "Contact name",
"example": "ABC Inc."
},
"vatId": {
"type": "string",
"description": "Vat ID",
"example": "DE123456789",
"nullable": true
},
"taxNumber": {
"type": "string",
"description": "Tax number",
"example": "12345678901",
"nullable": true
},
"paymentType": {
"type": "string",
"description": "Payment Type",
"example": "SEPA",
"enum": [
"SEPA",
"INTERNATIONAL"
],
"default": "SEPA"
},
"iban": {
"type": "string",
"description": "IBAN – This field is ignored for international payments.",
"example": "DE12345678901234567890",
"nullable": true
},
"bic": {
"type": "string",
"description": "BIC/SWIFT – This field is ignored for international payments.",
"example": "BIC123456789",
"nullable": true
},
"paymentConditionName": {
"type": "string",
"description": "Payment Condition Attached to the Contact",
"example": "PC 1",
"nullable": true
}
},
"required": [
"accountReceivableNumber",
"name"
]
},
{
"title": "Creditor Contact",
"type": "object",
"properties": {
"accountPayableNumber": {
"type": "string",
"description": "Account Payable number",
"example": "S742932"
},
"name": {
"type": "string",
"description": "Contact name",
"example": "ABC Inc."
},
"vatId": {
"type": "string",
"description": "Vat ID",
"example": "DE123456789",
"nullable": true
},
"taxNumber": {
"type": "string",
"description": "Tax number",
"example": "12345678901",
"nullable": true
},
"paymentType": {
"type": "string",
"description": "Payment Type",
"example": "SEPA",
"enum": [
"SEPA",
"INTERNATIONAL"
],
"default": "SEPA"
},
"iban": {
"type": "string",
"description": "IBAN – This field is ignored for international payments.",
"example": "DE12345678901234567890",
"nullable": true
},
"bic": {
"type": "string",
"description": "BIC/SWIFT – This field is ignored for international payments.",
"example": "BIC123456789",
"nullable": true
},
"paymentConditionName": {
"type": "string",
"description": "Payment Condition Attached to the Contact",
"example": "PC 1",
"nullable": true
}
},
"required": [
"accountPayableNumber",
"name"
]
}
]
}
}
}
}
},
"responses": {
"202": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"processId": {
"type": "string",
"description": "The unique identifier of the import request.",
"example": "9924bb4a-7ee9-4b6a-ac7b-30fdbe6b0031"
}
},
"required": [
"processId"
]
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errorCode": {
"type": "string",
"description": "The Error Code assigned to the issue encountered",
"enum": [
"UNAUTHORIZED",
"FORBIDDEN",
"BAD_REQUEST",
"SERVICE_UNAVAILABLE",
"INTERNAL_SERVER_ERROR",
"MISSING_REQUESTER_ID",
"BAD_INPUT",
"NOT_FOUND",
"EXPORTABLE_POSTINGS_NOT_FOUND",
"TOO_MANY_REQUEST",
"FAILED_TO_FETCH_DOWNLOAD_URL",
"FILE_NOT_FOUND"
]
},
"message": {
"type": "string",
"description": "Description about the issue encountered"
},
"requestId": {
"type": "string",
"description": "This is the unique identifier for the request."
},
"errors": {
"description": "This is an optional output that can provide more details about the input parameters that may have caused an issue.",
"type": "array",
"items": {
"type": "object",
"properties": {
"index": {
"type": "string",
"description": "This identifies the index of the payload that has an issue."
},
"property": {
"type": "string",
"description": "This identifies the parameter that has an issue."
},
"messages": {
"description": "This provides more details about the parameter that has an issue.",
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"property",
"messages"
]
}
}
},
"required": [
"errorCode",
"message"
]
}
}
}
},
"429": {
"description": "The request limit or the per-record limit for this endpoint has been exceeded. No records were imported, so the same request body can be resubmitted unchanged once the wait has elapsed.\n\nSee the [Rate Limiting Policy](https://developer.candis.io/docs/rate-limiting-policy) for the limits, response headers and retry guidance.",
"headers": {
"Retry-After": {
"description": "Whole seconds to wait before retrying. See the Rate Limiting Policy for how the value is derived.",
"schema": {
"type": "integer",
"example": 10
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errorCode": {
"type": "string",
"description": "The Error Code assigned to the issue encountered",
"enum": [
"UNAUTHORIZED",
"FORBIDDEN",
"BAD_REQUEST",
"SERVICE_UNAVAILABLE",
"INTERNAL_SERVER_ERROR",
"MISSING_REQUESTER_ID",
"BAD_INPUT",
"NOT_FOUND",
"EXPORTABLE_POSTINGS_NOT_FOUND",
"TOO_MANY_REQUEST",
"FAILED_TO_FETCH_DOWNLOAD_URL",
"FILE_NOT_FOUND"
]
},
"message": {
"type": "string",
"description": "Description about the issue encountered"
},
"requestId": {
"type": "string",
"description": "This is the unique identifier for the request."
},
"limit": {
"type": "string",
"description": "Which limit rejected the request: the request limit, which counts requests, or the record limit, which meters the records in the request body.",
"enum": [
"request",
"record"
]
},
"scope": {
"type": "string",
"description": "Whose allowance was exhausted: the organization’s own, or the shared allowance of the holding it belongs to.",
"enum": [
"organization",
"holding"
]
}
},
"required": [
"errorCode",
"message"
]
}
}
}
},
"503": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errorCode": {
"type": "string",
"description": "The Error Code assigned to the issue encountered",
"enum": [
"UNAUTHORIZED",
"FORBIDDEN",
"BAD_REQUEST",
"SERVICE_UNAVAILABLE",
"INTERNAL_SERVER_ERROR",
"MISSING_REQUESTER_ID",
"BAD_INPUT",
"NOT_FOUND",
"EXPORTABLE_POSTINGS_NOT_FOUND",
"TOO_MANY_REQUEST",
"FAILED_TO_FETCH_DOWNLOAD_URL",
"FILE_NOT_FOUND"
]
},
"message": {
"type": "string",
"description": "Description about the issue encountered"
},
"requestId": {
"type": "string",
"description": "This is the unique identifier for the request."
}
},
"required": [
"errorCode",
"message"
]
}
}
}
}
},
"security": [
{
"bearer": []
}
],
"summary": "Create Contacts",
"tags": [
"Core Data"
]
}
}
},
"info": {
"title": "Candis API",
"version": "1.0",
"description": "",
"contact": {},
"x-logo": {
"url": "https://www.candis.io/img/candis-logo-black.svg",
"altText": "Candis GmbH"
}
},
"servers": [
{
"url": "https://api.candis.io"
},
{
"description": "Candis API Authorization Server.",
"url": "https://id.my.candis.io/auth/realms/candis/protocol/openid-connect"
}
],
"components": {
"securitySchemes": {
"bearer": {
"scheme": "bearer",
"bearerFormat": "JWT",
"type": "http"
}
}
}
}
```