--- updatedAt: 2026-06-18T06:12:47.000Z agentTools: projectIndex: https://developer.hellozai.com/llms.txt --- # Create User Create a **User** that can be associated with **Items** as either a buyer or a seller. **Users** can't be both the buyer and seller for the same **Item**. You can also use this endpoint to create a **company** for the user. To create a company for the user, you need to send company parameters in the same request. **Note**: Some parameters are required for user verification. See our guide on [Onboarding a Payout User/Seller](https://developer.hellozai.com/docs/onboarding-a-pay-out-user) for more information. # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "title": "Assembly API", "description": "Assembly (formely PromisePay) is a powerful payments engine custom-built for platforms and marketplaces.", "version": "2.4", "contact": { "email": "support@assemblypayments.com", "url": "http://docs.assemblypayments.com/" } }, "servers": [ { "url": "https://test.api.promisepay.com", "description": "Pre-live environment" }, { "url": "https://secure.api.promisepay.com", "description": "Production environment" }, { "url": "https://au-0000.sandbox.auth.assemblypay.com", "description": "Pre-Live (Sandbox) Auth issuing server and API" }, { "url": "https://au-0000.auth.assemblypay.com", "description": "Production Auth issuing server and API" }, { "description": "SwaggerHub API Auto Mocking", "url": "https://virtserver.swaggerhub.com/AssemblyPlatforms/assembly-api/2.1" } ], "x-explorer-enabled": false, "x-samples-languages": [ "curl", "ruby", "php", "javascript", "csharp", "go" ], "paths": { "/users": { "post": { "tags": [ "Users" ], "summary": "Create User", "description": "Create a **User** that can be associated with **Items** as either a buyer or a seller. **Users** can't be both the buyer and seller for the same **Item**. You can also use this endpoint to create a **company** for the user. To create a company for the user, you need to send company parameters in the same request. **Note**: Some parameters are required for user verification. See our guide on [Onboarding a Payout User/Seller](https://developer.hellozai.com/docs/onboarding-a-pay-out-user) for more information.\n", "operationId": "createUser", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user_requestBody" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/single_user" }, "examples": { "response": { "value": { "users": { "created_at": "2019-04-29T02:47:08.348Z", "updated_at": "2019-04-29T02:47:08.348Z", "full_name": "Neol1556506027 Calangi", "email": "neol.calangi+buyer1556506027@promisepay.com", "mobile": "+21556506027", "phone": null, "logo_url": null, "color_1": null, "color_2": null, "first_name": "Neol1556506027", "last_name": "Calangi", "id": "buyer-1556506027", "custom_descriptor": null, "location": "AUS", "verification_state": "pending", "held_state": false, "roles": [ "customer" ], "dob": "encrypted", "government_number": null, "drivers_license": null, "flags": {}, "related": { "addresses": "00eb5be0-4c57-0137-ad3d-0242ac110002" }, "links": { "self": "/charges/4d7d73f5-c7f0-477d-aff8-7570d2c7e7d9/buyers", "items": "/users/buyer-1556506027/items", "card_accounts": "/users/buyer-1556506027/card_accounts", "paypal_accounts": "/users/buyer-1556506027/paypal_accounts", "payid_accounts": "/users/buyer-1556506027/payid_accounts", "bank_accounts": "/users/buyer-1556506027/bank_accounts", "wallet_accounts": "/users/buyer-1556506027/wallet_accounts" } } } } } } } } } } } }, "components": { "schemas": { "single_user": { "type": "object", "properties": { "users": { "$ref": "#/components/schemas/user" } } }, "user": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "full_name": { "type": "string", "example": "Samuel Seller" }, "email": { "type": "string", "format": "email", "example": "samuel.seller@assemblypayments.com" }, "mobile": { "type": "string", "example": 61491570156 }, "phone": { "type": "string" }, "logo_url": { "type": "string" }, "color_1": { "type": "string" }, "color_2": { "type": "string" }, "first_name": { "type": "string", "example": "Samuel" }, "last_name": { "type": "string", "example": "Seller" }, "id": { "type": "string", "example": "Seller_1234" }, "custom_descriptor": { "type": "string" }, "location": { "type": "string", "example": "AUS" }, "verification_status": { "type": "string", "example": "pending" }, "held_state": { "type": "boolean", "example": false }, "roles": { "type": "array", "items": { "type": "string", "example": "customer" } }, "dob": { "type": "string", "example": "encrypted" }, "government_number": { "type": "string", "example": "encrypted" }, "drivers_license": { "type": "string" }, "flags": { "type": "object" }, "related": { "type": "object", "properties": { "addresses": { "type": "string", "example": "fe602dcf-4175-4f88-b5be-3beb04092dcd" } } }, "links": { "type": "object", "properties": { "self": { "type": "string" }, "items": { "type": "string" }, "card_accounts": { "type": "string" }, "paypal_accounts": { "type": "string" }, "payid_accounts": { "type": "string" }, "bpay_accounts": { "type": "string" }, "bank_accounts": { "type": "string" }, "wallet_accounts": { "type": "string" } } } } }, "user_requestBody": { "type": "object", "required": [ "id", "first_name", "last_name", "email", "country" ], "properties": { "id": { "description": "Unique ID that can be generated by the platform. Cannot contain '.' character. Contact Assembly support if you want user IDs to be generated automatically.", "type": "string", "example": "buyer-1556506027", "default": "buyer-1556506027" }, "first_name": { "description": "First name of the user", "type": "string", "example": "Neol1556506027", "default": "Neol1556506027" }, "last_name": { "description": "Last name of the user", "type": "string", "example": "Calangi", "default": "Calangi" }, "email": { "description": "Email of the user. Unique to platform.", "type": "string", "example": "neol.calangi+buyer1556506027@promisepay.com", "default": "neol.calangi+buyer1556506027@promisepay.com" }, "mobile": { "description": "International number format. Include '+' and no spaces.", "type": "string", "example": "+21556506027" }, "address_line1": { "description": "First line of the user address", "type": "string", "example": "" }, "address_line2": { "description": "Second line of the user address", "type": "string", "example": "" }, "state": { "description": "State section of the user address", "type": "string", "example": "" }, "city": { "description": "City section of the user address", "type": "string", "example": "" }, "zip": { "description": "Postcode", "type": "string", "example": "" }, "country": { "description": "[ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3#Officially_assigned_code_elements) country code (3 char)", "type": "string", "example": "AUS", "default": "AUS" }, "dob": { "description": "Date of Birth (DD/MM/YYYY).", "type": "string", "example": null }, "government_number": { "description": "Generic parameter to capture important user verification data. eg. SSN for US users, TFN for AU users.", "type": "string", "example": "" }, "drivers_license_number": { "description": "Driving license number of the user", "type": "string", "example": "" }, "drivers_license_state": { "description": "State section of the user's driving license", "type": "string", "example": "" }, "ip_address": { "description": "IP address", "type": "string", "example": "" }, "logo_url": { "description": "URL link to the logo", "type": "string", "example": "" }, "color_1": { "description": "Color code number 1", "type": "string", "example": "" }, "color_2": { "description": "Color code number 2", "type": "string", "example": "" }, "custom_descriptor": { "description": "When custom_descriptors are enabled, this is the information to appear on bundle direct debit statements (which show the buyer's custom_descriptor) as well as international wire payout, direct credit and PayPal payout statements (which show the seller's custom_descriptor)", "type": "string", "example": "" }, "authorized_signer_title": { "description": "‘Authorised Signer Title’, which refers to the role / job title (e.g. Director or General Manager) for the individual User, who is authorised to sign contracts on behalf of the business entity / Merchant User. (Note: information required for AMEX Merchants)", "type": "string", "example": "Director" }, "company": { "required": [ "country", "legal_name", "name", "tax_number", "business_email" ], "type": "object", "description": "This is an optional field and if provided, the company will be created for the user.", "properties": { "name": { "type": "string", "description": "Company name", "example": "ABC", "default": "ABC" }, "legal_name": { "type": "string", "description": "Company legal name", "example": "ABC Pty Ltd", "default": "ABC Pty Ltd" }, "tax_number": { "type": "string", "description": "ABN / TFN", "example": "123456789", "default": "123456789" }, "business_email": { "description": "The business email address associated with the user or business.", "type": "string", "example": "test@sample.com" }, "charge_tax": { "type": "boolean", "description": "Charge GST? Use the value True to charge GST. Use False to not charge GST.", "nullable": true, "example": false }, "address_line1": { "type": "string", "description": "Address line 1", "example": "Collins" }, "address_line2": { "type": "string", "description": "Address line 2", "example": "" }, "city": { "type": "string", "description": "City", "example": "Melbourne" }, "state": { "type": "string", "description": "State", "example": "VIC" }, "zip": { "type": "string", "description": "Zip", "example": "3000" }, "country": { "type": "string", "description": "2 or 3 letter country code. (e.g. AUS)", "example": "AUS", "default": "AUS" }, "phone": { "type": "string", "description": "Company phone number", "example": "", "default": "" } } } } } }, "securitySchemes": { "oAuth2ClientCredentials": { "type": "oauth2", "description": "Please refer to Authentication section within https://developer.assemblypayments.com/reference#authentication", "flows": { "clientCredentials": { "tokenUrl": "https://au-0000.sandbox.auth.assemblypay.com/tokens", "scopes": {} } } } } }, "security": [ { "oAuth2ClientCredentials": [] } ], "x-proxy-enabled": true, "x-samples-enabled": true } ```