For AI agents: markdown of this page — /docs-content-en/entities/person-types/create.md documentation index — /llms.txt

Create a payer type

POST /v1/person-types

Adds a payer type to the online store list for use in orders and order properties.

Pass fields at the root of the JSON object, without a fields wrapper.

Request body fields

Field Type Required Description
name string yes Payer type name
code string | null no Unique code. Must differ from the code of any other type
sort number no Sort order
active boolean no Whether the type is active
xmlId string | null no External ID

For the full field list, see GET /v1/person-types/fields.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/person-types" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Documentation payer type",
  "code": "DOCS_PERSON_397F55D8FB1D",
  "xmlId": "DOCS_PERSON_397F55D8FB1D",
  "sort": 900,
  "active": false
}'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/person-types" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Documentation payer type",
  "code": "DOCS_PERSON_397F55D8FB1D",
  "xmlId": "DOCS_PERSON_397F55D8FB1D",
  "sort": 900,
  "active": false
}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/person-types', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Documentation payer type',
    code: 'DOCS_PERSON_397F55D8FB1D',
    xmlId: 'DOCS_PERSON_397F55D8FB1D',
    sort: 900,
    active: false,
  }),
})

const { success, data } = await res.json()

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/person-types', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Documentation payer type',
    code: 'DOCS_PERSON_397F55D8FB1D',
    xmlId: 'DOCS_PERSON_397F55D8FB1D',
    sort: 900,
    active: false,
  }),
})

const { success, data } = await res.json()

Response fields

Field Type Description
success boolean true on success. The HTTP status is 201
data object Created payer type
data.id number RO. Payer type ID
data.name string Name
data.code string | null Unique code
data.sort number Sort order
data.active boolean Whether the type is active
data.xmlId string | null External ID

Response example

JSON 
{
  "success": true,
  "data": {
    "active": false,
    "code": "DOCS_PERSON_397F55D8FB1D",
    "id": 21,
    "name": "Documentation payer type",
    "sort": 900,
    "xmlId": "DOCS_PERSON_397F55D8FB1D"
  }
}

Error response example

422 — the code is already used by another payer type:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "person type code exists",
    "b24Code": "200750000005"
  }
}

Errors

HTTP Code Description
400 MISSING_REQUIRED_FIELDS The name field is missing or empty
400 READONLY_FIELD A read-only field was provided: id or lid
400 INVALID_PARAMS A scalar field received an object or array, such as an object in active
422 BITRIX_ERROR The code is already in use. Message: person type code exists, b24Code: 200750000005
422 BITRIX_ERROR Bitrix24 rejected creation for another reason. The reason is in message
403 BITRIX_ACCESS_DENIED The key owner lacks permission to modify payer types in Bitrix24
403 WRITE_BLOCKED_READONLY_KEY The key is in read-only mode
403 SCOPE_DENIED The API key lacks the sale scope
401 MISSING_API_KEY The X-Api-Key header is missing
401 TOKEN_MISSING The API key has no configured tokens

For the full list of common API errors, see Error codes.

See also