> For the complete documentation index, see [llms.txt](https://invoice4u.gitbook.io/invoice4u-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://invoice4u.gitbook.io/invoice4u-docs/customers/create-customer.md). # Create a Customer Creates a customer in the authenticated organization. If `ID` is supplied and exists, the call behaves like an update. ## Endpoint | | | | ------------ | ---------------------------------------------------------- | | **Method** | `POST` | | **Path** | `/CreateCustomer` | | **Response** | `Customer` object (check `Errors` and negative `ID` codes) | Variants: | Path | Method | Auth | Notes | | --------------------------- | ------ | -------------- | ------------------------------------------------------------------------------------------------------------------------- | | `/CreateCustomer` | POST | token | Standard — full `Customer` object. | | `/CreateCustomerREST` | GET | email+password | Query-string variant. | | `/CreateCustomerParamsREST` | GET | email+password | Flat parameters (`name`, `customerEmail`, `uniqueId`, `phone`, `cell`, `externalNumber`); always allows non-unique names. | ## Request schema | Field | Type | Required | Description | | ------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `cu` | Customer | Yes | The customer to create. See [the Customer object](/invoice4u-docs/customers/overview.md#the-customer-object). Minimum: `Name`. `UniqueID`, if given, must be numeric. | | `token` | string | Yes | Authentication token. | ## Example request ```http POST /Services/ApiService.svc/CreateCustomer HTTP/1.1 Host: apiqa.invoice4u.co.il Content-Type: application/json { "cu": { "Name": "Acme Ltd", "UniqueID": "512345678", "Email": "billing@acme.example", "Phone": "03-1234567", "Cell": "050-1234567", "Address": "1 Herzl St", "City": "Tel Aviv", "ExtNumber": 10045, "Active": true, "PayTerms": 30 }, "token": "" } ``` ## Example response ```json { "CreateCustomerResult": { "ID": 88231, "Name": "Acme Ltd", "UniqueID": "512345678", "Email": "billing@acme.example", "ExtNumber": 10045, "OrgID": 12345, "Active": true, "Errors": [] } } ``` ## Errors | Error (ID) | Meaning | | ------------------------------------------------ | ------------------------------------------------------------- | | `UnauthorizedUser` (80) | Invalid token. | | `CustomerNameCanNotBeEmpty` (28) | `Name` missing. | | `CustomerUniqueIdNotNumeric` (79) | `UniqueID` contains non-digits. | | `CustomerNameExists` (2) / `ID = -1` | Duplicate name. Set `IsNonUniqueNameCreation: true` to allow. | | `CustomerExternalNumberExists` (31) / `ID = -2` | Duplicate `ExtNumber`. | | `CustomerUniqueIdExistsForUser` (78) / `ID = -3` | Duplicate `UniqueID`. | | `CustomerGuidExists` (84) / `ID = -4` | Duplicate `Guid`. | | `ClientDoesntExists` (7) | `ID` supplied but no such customer (update path). | ## Try it ## Create a customer > Creates a customer in the authenticated organization. If \`cu.ID\` exists, behaves like an update. Negative returned ID = conflict: -1 name, -2 external number, -3 unique ID, -4 GUID. ```json {"openapi":"3.0.3","info":{"title":"Invoice4U API","version":"1.0.0"},"tags":[{"name":"Customers","description":"Create, update and retrieve customers."}],"servers":[{"url":"https://api.invoice4u.co.il/Services/ApiService.svc","description":"Production"},{"url":"https://apiqa.invoice4u.co.il/Services/ApiService.svc","description":"QA (staging)"}],"paths":{"/CreateCustomer":{"post":{"tags":["Customers"],"operationId":"CreateCustomer","summary":"Create a customer","description":"Creates a customer in the authenticated organization. If `cu.ID` exists, behaves like an update. Negative returned ID = conflict: -1 name, -2 external number, -3 unique ID, -4 GUID.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cu","token"],"properties":{"cu":{"$ref":"#/components/schemas/Customer"},"token":{"type":"string"}}}}}},"responses":{"200":{"description":"The created customer.","content":{"application/json":{"schema":{"type":"object","properties":{"CreateCustomerResult":{"$ref":"#/components/schemas/Customer"}}}}}}}}}},"components":{"schemas":{"Customer":{"allOf":[{"$ref":"#/components/schemas/CommonObject"},{"type":"object","required":["Name"],"properties":{"ID":{"type":"integer","description":"0/omitted on create; required on update. Negative values are conflict codes: -1 name, -2 external number, -3 unique ID, -4 GUID."},"Name":{"type":"string"},"UniqueID":{"type":"string","nullable":true,"description":"VAT/company/ID number. Digits only."},"Email":{"type":"string","nullable":true},"Phone":{"type":"string","nullable":true},"Cell":{"type":"string","nullable":true},"Fax":{"type":"string","nullable":true},"Address":{"type":"string","nullable":true},"City":{"type":"string","nullable":true},"Zip":{"type":"string","nullable":true},"Country":{"type":"string","nullable":true},"CountryId":{"type":"integer","nullable":true},"ExtNumber":{"type":"integer","format":"int64","nullable":true,"description":"Your external customer number. Unique per organization."},"Active":{"type":"boolean"},"PayTerms":{"type":"integer","description":"Payment terms in days (0 = due now, 30 = EOM+30, ...)."},"IsNonUniqueNameCreation":{"type":"boolean","nullable":true,"description":"Allow duplicate names. Default false."},"Guid":{"type":"string","nullable":true,"description":"Your external GUID. Unique per organization."},"ClientCode":{"type":"integer"},"ContactFirstName":{"type":"string","nullable":true},"ContactLastName":{"type":"string","nullable":true},"ContactName":{"type":"string","nullable":true},"ContactEmail":{"type":"string","nullable":true},"CustomerEmails":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/AssociatedEmail"}},"AccountNumber":{"type":"string","nullable":true},"BankName":{"type":"string","nullable":true},"BranchName":{"type":"string","nullable":true},"Website":{"type":"string","nullable":true},"InternalNote":{"type":"string","nullable":true},"OrgID":{"type":"integer","readOnly":true}}}]},"CommonObject":{"type":"object","description":"Response envelope inherited by most objects. Server-generated — never send these fields in requests. Always check Errors before using the payload.","properties":{"Errors":{"type":"array","readOnly":true,"items":{"$ref":"#/components/schemas/CommonError"}},"Info":{"type":"array","readOnly":true,"items":{"$ref":"#/components/schemas/CommonInfo"}},"OpenInfo":{"type":"object","readOnly":true,"additionalProperties":{"type":"string"},"nullable":true}}},"CommonError":{"type":"object","properties":{"ID":{"type":"integer","description":"Numeric error code, e.g. 80 = UnauthorizedUser, 134 = DocumentAlreadyCreated."},"Error":{"type":"string","description":"Error name."},"Paramters":{"type":"string","nullable":true,"description":"Optional context, e.g. \"Row Number - 0\"."}}},"CommonInfo":{"type":"object","properties":{"ID":{"type":"integer"},"Info":{"type":"string"},"Paramters":{"type":"string","nullable":true}}},"AssociatedEmail":{"type":"object","required":["Mail"],"properties":{"Mail":{"type":"string","format":"email"},"IsUserMail":{"type":"boolean","description":"true marks the copy sent to the account owner."},"ClientId":{"type":"integer","nullable":true},"IsSendDoc":{"type":"boolean","nullable":true}}}}}} ```