> ## Documentation Index > Fetch the complete documentation index at: https://docs.xendit.co/llms.txt > Use this file to discover all available pages before exploring further. # Create customer request > Make a POST request to this endpoint to create a customer for later use with a payments endpoint. The Customer Object is a standard data structure to hold information relating to one of your customers. It has the following major components: - A Type of customer (Individual or Business) - Basic descriptive details of that customer - Addresses of the customer - Identity accounts and KYC documents to prove the legitimacy of the customer - Other metadata ## OpenAPI ````json POST /customers { "openapi": "3.0.0", "info": { "title": "Others", "version": "3.0.0", "description": "These APIs provide merchants with customer management, file operations, and bill payment capabilities.\n\nThey cover:\n- Customer profile management\n- File upload, retrieval, and management\n- Bill payment services for utility providers and billers in Indonesia\n", "contact": { "name": "Xendit API Support", "email": "help@xendit.co", "url": "https://www.xendit.co/support" }, "license": { "name": "Proprietary", "url": "https://www.xendit.co/terms-and-conditions/" } }, "servers": [ { "url": "https://api.xendit.co", "description": "Xendit API" } ], "tags": [ { "name": "Customers", "description": "Operations for managing customer profiles and information" }, { "name": "Files", "description": "Operations for file upload, retrieval, and management" }, { "name": "Bill Payments", "description": "Bill payment services for utility providers and billers in Indonesia" } ], "paths": { "/customers": { "post": { "security": [ { "BasicAuth": [] } ], "operationId": "CreateCustomer", "summary": "Create customer request", "description": "Make a POST request to this endpoint to create a customer for later use with a payments endpoint.\n\nThe Customer Object is a standard data structure to hold information relating to one of your customers. It has the following major components:\n- A Type of customer (Individual or Business)\n- Basic descriptive details of that customer\n- Addresses of the customer\n- Identity accounts and KYC documents to prove the legitimacy of the customer\n- Other metadata\n", "tags": [ "Customers" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyHeader" }, { "$ref": "#/components/parameters/CustAPIVersionHeader" }, { "$ref": "#/components/parameters/ForUserIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomerObject" } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerObject" }, "examples": { "getIndividualCustomer": { "value": { "id": "cust-239c16f4-866d-43e8-9341-7badafbc019f", "reference_id": "demo_1475801962607", "type": "INDIVIDUAL", "individual_detail": { "given_names": "John", "surname": "Doe", "nationality": "ID", "place_of_birth": "Jakarta", "date_of_birth": "1980-01-01", "gender": "MALE", "employment": { "employer_name": "Xendit", "nature_of_business": "Payment Gateway", "role_description": "Test dummy" } }, "email": "customer@website.com", "mobile_number": "+62812123456", "phone_number": "+62812123456", "hashed_phone_number": "+628#######56", "addresses": [ { "street_line1": "Panglima Polim IV", "street_line2": "Ruko Grand Panglima Polim, Blok E", "city": "Jakarta Selatan", "province_state": "DKI Jakarta", "postal_code": "993448", "country": "ID", "category": "HOME", "is_primary": true } ], "kyc_documents": [ { "type": "IDENTITY_CARD", "sub_type": "NATIONAL_ID", "country": "ID", "document_name": "KTP", "document_number": "12356789012456", "expires_at": null, "holder_name": "John Doe", "document_images": [ "file-ec700c1c-db17-4496-b1fb-04ebe551b412" ] } ], "description": "My first customer", "date_of_registration": "2020-03-30", "domicile_of_registration": "ID", "metadata": { "foo": "bar" }, "created": "2020-03-30T06:12:47.212Z", "updated": "2020-03-30T06:12:47.212Z" } }, "getBusinessCustomer": { "value": { "id": "cust-239c16f4-866d-43e8-9341-7badafbc019f", "reference_id": "demo_1475801962607", "type": "BUSINESS", "business_detail": { "business_name": "ACME Corp", "trading_name": null, "business_type": "CORPORATION", "nature_of_business": null, "business_domicile": null, "date_of_registration": null }, "email": "customer@website.com", "mobile_number": null, "phone_number": null, "hashed_phone_number": null, "addresses": [], "kyc_documents": [], "description": null, "date_of_registration": "2020-03-30", "domicile_of_registration": "ID", "metadata": {}, "created": "2020-03-30T06:12:47.212Z", "updated": "2020-03-30T06:12:47.212Z" } } } } } }, "409": { "$ref": "#/components/responses/ErrorStatusCode409Response" } } } } }, "components": { "parameters": { "IdempotencyKeyHeader": { "in": "header", "name": "idempotency-key", "description": "A unique key to prevent processing duplicate requests. Can be your reference_id or any GUID. Must be unique across development & production environments. Idempotency keys are stored on the request layer; it expires after 24 hours from the first request", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 100, "example": "ef73608e-51d1-4770-8396-08a44dd4c9f0" } }, "CustAPIVersionHeader": { "in": "header", "name": "api-version", "description": "API version in date semantic. Attach this parameter when calling a specific API version. List of API versions can be found here.", "required": false, "schema": { "example": "2020-10-31", "type": "string", "enum": [ "2020-10-31", "2020-05-19" ] } }, "ForUserIdHeader": { "in": "header", "name": "for-user-id", "description": "The sub-account user-id that you want to make this transaction for.\n\nThis header is only used if you have access to xenPlatform. See xenPlatform for more information\n", "required": false, "schema": { "type": "string" } } }, "schemas": { "CreateCustomerObject": { "type": "object", "description": "Create body request", "properties": { "reference_id": { "$ref": "#/components/schemas/ReferenceId" }, "type": { "$ref": "#/components/schemas/CustomerType" }, "individual_detail": { "$ref": "#/components/schemas/XenditStandardIndividualDetail" }, "business_detail": { "$ref": "#/components/schemas/XenditStandardBusinessDetail" }, "mobile_number": { "$ref": "#/components/schemas/MobileNumber" }, "phone_number": { "$ref": "#/components/schemas/PhoneNumber" }, "email": { "$ref": "#/components/schemas/Email" }, "addresses": { "$ref": "#/components/schemas/XenditStandardAddress" }, "kyc_documents": { "$ref": "#/components/schemas/XenditKYCDocuments" }, "description": { "$ref": "#/components/schemas/Description" }, "date_of_registration": { "type": "string", "description": "Business registration date", "format": "date" }, "domicile_of_registration": { "type": "string", "description": "Country within which the account that the shopper had to create/sign up on the merchant's website resides (e.g. accounts created on Shopee SG have `SG` as the value for this field. ISO 3166-2 Country Code", "minLength": 2, "maxLength": 2 }, "metadata": { "type": "object", "description": "Object of additional information related to the customer. Define the JSON properties and values as required to pass information through the APIs.\nYou can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long.\nThis is only for your use and will not be used by Xendit.\n" } }, "required": [ "reference_id", "type" ] }, "CustomerObject": { "type": "object", "description": "Customer Object", "properties": { "id": { "$ref": "#/components/schemas/CustomerId" }, "reference_id": { "$ref": "#/components/schemas/ReferenceId" }, "type": { "type": "string", "enum": [ "INDIVIDUAL", "BUSINESS" ], "description": "Type of customer" }, "individual_detail": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/XenditStandardIndividualDetail" } ] }, "business_detail": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/XenditStandardBusinessDetail" } ] }, "mobile_number": { "$ref": "#/components/schemas/PhoneNumber" }, "phone_number": { "$ref": "#/components/schemas/MobileNumber" }, "hashed_phone_number": { "$ref": "#/components/schemas/HashedPhoneNumber" }, "email": { "$ref": "#/components/schemas/Email" }, "addresses": { "type": "array", "items": { "$ref": "#/components/schemas/XenditStandardAddress" } }, "identity_accounts": { "type": "array", "items": { "$ref": "#/components/schemas/IdentityAccount" } }, "kyc_documents": { "$ref": "#/components/schemas/XenditKYCDocuments" }, "description": { "$ref": "#/components/schemas/Description" }, "date_of_registration": { "type": "string", "description": "Date of which the account that the shopper had to create/sign up on the merchant's website", "format": "date" }, "domicile_of_registration": { "type": "string", "description": "Country within which the account that the shopper had to create/sign up on the merchant's website resides (e.g. accounts created on Shopee SG have `SG` as the value for this field. ISO 3166-2 Country Code", "minLength": 2, "maxLength": 2 }, "metadata": { "type": "object", "description": "Object of additional information related to the customer. Define the JSON properties and values as required to pass information through the APIs.\nYou can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long.\nThis is only for your use and will not be used by Xendit.\n" }, "created": { "type": "string", "format": "date-time", "description": "Customer creation timestamp" }, "updated": { "type": "string", "format": "date-time", "description": "Customer last update timestamp" } }, "required": [ "reference_id" ] }, "ReferenceId": { "type": "string", "minLength": 1, "maxLength": 255, "description": "A Reference ID from merchants to identify their request." }, "CustomerType": { "type": "string", "enum": [ "INDIVIDUAL", "BUSINESS" ], "description": "Type of customer" }, "XenditStandardIndividualDetail": { "type": "object", "required": [ "given_names" ], "description": "JSON object containing details of the Individual. Required if type is `INDIVIDUAL`", "properties": { "given_names": { "type": "string", "description": "Primary or first name/s of customer. Alphanumeric. No special characters is allowed.", "minLength": 1, "maxLength": 50 }, "surname": { "type": "string", "nullable": true, "description": "Last or family name of customer. Alphanumeric. No special characters is allowed.", "minLength": 1, "maxLength": 50 }, "nationality": { "type": "string", "nullable": true, "description": "Country code for customer nationality. ISO 3166-1 alpha-2 Country Code", "minLength": 2, "maxLength": 2 }, "place_of_birth": { "type": "string", "nullable": true, "description": "City or other relevant location for the customer birth place. Alphanumeric. No special characters is allowed.", "minLength": 1, "maxLength": 60 }, "date_of_birth": { "type": "string", "nullable": true, "description": "Date of birth of the customer. Format: YYYY-MM-DD", "minLength": 10, "maxLength": 10 }, "gender": { "type": "string", "nullable": true, "enum": [ "MALE", "FEMALE", "OTHER" ], "description": "Gender of customer" }, "employment": { "type": "object", "nullable": true, "properties": { "employer_name": { "type": "string", "description": "Name of the employer", "minLength": 1, "maxLength": 50 }, "nature_of_business": { "type": "string", "description": "Industry or nature of business", "minLength": 1, "maxLength": 50 }, "role_description": { "type": "string", "description": "Occupation or title", "minLength": 1, "maxLength": 50 } } } } }, "XenditStandardBusinessDetail": { "type": "object", "required": [ "business_name" ], "description": "JSON object containing details of the business. Required if type is `BUSINESS`", "properties": { "business_name": { "type": "string", "description": "Name of business", "minLength": 1, "maxLength": 50 }, "trading_name": { "type": "string", "nullable": true, "description": "Trading name", "minLength": 1, "maxLength": 50 }, "business_type": { "type": "string", "description": "Legal entity type of the business", "enum": [ "SOLE_PROPRIETOR", "PARTNERSHIP", "COOPERATIVE", "TRUST", "NON_PROFIT", "GOVERNMENT", "CORPORATION" ] }, "nature_of_business": { "type": "string", "nullable": true, "description": "Free text description of the type of business this entity pursues", "minLength": 1, "maxLength": 50, "example": "Ecommerce, Travel" }, "business_domicile": { "type": "string", "nullable": true, "description": "Registered country of the business. ISO 3166 format" }, "date_of_registration": { "type": "string", "nullable": true, "description": "Business registration date", "format": "date" } } }, "MobileNumber": { "type": "string", "nullable": true, "minLength": 7, "maxLength": 15, "description": "Supports both E.164 international format (+) and local formats with or without a leading zero.\n" }, "PhoneNumber": { "type": "string", "nullable": true, "description": "Supports both E.164 international format (+) and local formats with or without a leading zero.\n", "minLength": 7, "maxLength": 15 }, "Email": { "type": "string", "nullable": true, "format": "email", "description": "E-mail address of customer", "minLength": 1, "maxLength": 50 }, "XenditStandardAddress": { "type": "object", "required": [ "country" ], "properties": { "country": { "$ref": "#/components/schemas/Country" }, "street_line1": { "type": "string", "description": "Line 1 of street address e.g., building name and apartment number", "minLength": 1, "maxLength": 255 }, "street_line2": { "type": "string", "description": "Line 2 of street address e.g., building name and apartment number", "minLength": 1, "maxLength": 255 }, "city": { "type": "string", "description": "City, village or town of residence of customer", "minLength": 1, "maxLength": 255 }, "province_state": { "type": "string", "description": "Province, state or region of residence of customer", "minLength": 1, "maxLength": 255 }, "postal_code": { "type": "string", "description": "ZIP/Postal Code of customer", "minLength": 1, "maxLength": 255 }, "category": { "type": "string", "description": "Address type", "enum": [ "HOME", "WORK", "PROVINCIAL" ] }, "is_primary": { "type": "boolean", "description": "Defaults to false. Indicates that the information provided refers to the customer's primary address\n", "default": false } } }, "XenditKYCDocuments": { "type": "array", "items": { "$ref": "#/components/schemas/XenditKYCDocumentsObject" } }, "Description": { "type": "string", "nullable": true, "description": "Merchant-provided description for the customer. `Characters` alphanumeric. No special characters is allowed.", "minLength": 2, "maxLength": 500 }, "CustomerId": { "type": "string", "maxLength": 41, "description": "Xendit unique Capture ID generated as reference for the end user", "example": "cust-b98d6f63-d240-44ec-9bd5-aa42954c4f48" }, "HashedPhoneNumber": { "type": "string", "nullable": true, "description": "Hashed phone number", "minLength": 1, "maxLength": 250 }, "IdentityAccount": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of identity account", "enum": [ "CREDIT_CARD", "DEBIT_CARD", "BANK_ACCOUNT" ] }, "company": { "type": "string", "description": "Financial institution or company name" }, "description": { "type": "string", "description": "Description of the account" }, "country": { "$ref": "#/components/schemas/Country" }, "properties": { "type": "object", "description": "Additional properties specific to the account type" } } }, "Error409Schema": { "type": "object", "required": [ "error_code", "message" ], "properties": { "error_code": { "type": "string", "enum": [ "DUPLICATE_ERROR", "IDEMPOTENCY_ERROR" ] }, "message": { "type": "string" }, "errors": { "$ref": "#/components/schemas/XenditArrayOfErrors" } } }, "Country": { "type": "string", "description": "ISO 3166-1 alpha-2 Country Code", "minLength": 2, "maxLength": 2 }, "XenditKYCDocumentsObject": { "type": "object", "required": [ "country" ], "properties": { "country": { "$ref": "#/components/schemas/Country" }, "type": { "type": "string", "description": " Generic ID type", "enum": [ "BIRTH_CERTIFICATE", "BANK_STATEMENT", "DRIVING_LICENSE", "IDENTITY_CARD", "PASSPORT", "VISA", "BUSINESS_REGISTRATION", "BUSINESS_LICENSE" ] }, "sub_type": { "type": "string", "description": "Specific ID type for IDENTITY_CARD types", "enum": [ "NATIONAL_ID", "CONSULAR_ID", "VOTER_ID", "POSTAL_ID", "RESIDENCE_PERMIT", "TAX_ID", "STUDENT_ID", "MILITARY_ID", "MEDICAL_ID", "OTHERS" ] }, "document_name": { "type": "string", "description": "Free text description of the type of document (e.g., NIB, SIUP, AKTA). `Characters` alphanumeric. No special characters is allowed.", "maxLength": 255 }, "document_number": { "type": "string", "description": "Unique alphanumeric identity document number or code. `Characters` alphanumeric. No special characters is allowed.", "maxLength": 255 }, "expires_at": { "type": "string", "nullable": true, "description": "Expiry date, if relevant", "example": "2024-11-11" }, "holder_name": { "type": "string", "description": "Free text to capture the full name(s) of the individual or business as defined on the document, if relevant. `Characters` alphanumeric. No special characters is allowed.", "maxLength": 255 }, "document_images": { "type": "array", "items": { "type": "string" }, "description": "Array of file ids returned from uploads to the files endpoint, representing images of the front/back of the document, in png/jpg/jpeg/pdf format\n" } } }, "XenditArrayOfErrors": { "nullable": true, "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "object" } ] } } }, "responses": { "ErrorStatusCode409Response": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error409Schema" } } } } }, "securitySchemes": { "BasicAuth": { "type": "http", "scheme": "Basic" } } } } ````