> 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/get-customers.md).

# Retrieve Customers

Lookup endpoints for customers. All take a `token` and return either a single `Customer` or a collection. All results are scoped to the authenticated organization.

## Get by ID — `GetCustomerById`

|            |                    |
| ---------- | ------------------ |
| **Method** | `POST`             |
| **Path**   | `/GetCustomerById` |

```json
{ "custId": 88231, "token": "<token>" }
```

Returns the `Customer`. If the customer belongs to another organization: `ClientIDDoesntExists` (37).

## Get by name — `GetCustomerByName`

```json
{ "name": "Acme Ltd", "token": "<token>" }
```

`POST /GetCustomerByName` — exact-name lookup.

## Get by email — `GetCustomerByEmail`

```json
{ "email": "billing@acme.example", "name": "Acme Ltd", "token": "<token>" }
```

`POST /GetCustomerByEmail` — email lookup, with optional name to disambiguate.

## Get by GUID — `GetCustomerByGuid`

```json
{ "guid": "d2f1a6b3-...", "token": "<token>" }
```

`POST /GetCustomerByGuid` — lookup by the external `Guid` you set on creation. `GetCustomerByGuidInnerSearch` performs a broader (contains) search.

## Get by external number — `GetCustomerByExternalNumber`

```json
{ "number": 10045, "token": "<token>" }
```

`POST /GetCustomerByExternalNumber` — lookup by `ExtNumber`. Returns `CustomerNotFound` (136) when `number` is not positive.

## Get by client code — `GetCustomerByClientCode`

```json
{ "clientCode": 42, "token": "<token>" }
```

`POST /GetCustomerByClientCode` (alias: `/GetByClientCode`).

## Full record — `GetFullCustomer`

```json
{ "id": 88231, "orgID": 0, "token": "<token>" }
```

`POST /GetFullCustomer` — returns the full customer record including bank details, contacts and additional emails. Pass `orgID: 0` to use the token's organization.

## List all — `GetCustomersByOrgId`

```json
{ "token": "<token>" }
```

`POST /GetCustomersByOrgId` — returns `CommonCollection<Customer[]>`:

```json
{
  "GetCustomersByOrgIdResult": {
    "Response": [ { "ID": 88231, "Name": "Acme Ltd" }, ... ],
    "Errors": []
  }
}
```

## Search — `GetCustomers`

```json
{
  "cust": { "Name": "Acme" },
  "token": "<token>"
}
```

`POST /GetCustomers` — filtered search. Populate any subset of `Customer` fields (`Name`, `Email`, `UniqueID`, …) as the filter; returns a `CommonCollection<Customer[]>` of matches.

## Errors (all endpoints)

| Error (ID)                  | Meaning                                               |
| --------------------------- | ----------------------------------------------------- |
| `UnauthorizedUser` (80)     | Invalid token.                                        |
| `ClientIDDoesntExists` (37) | Customer not found / belongs to another organization. |
| `CustomerNotFound` (136)    | Invalid lookup value.                                 |
| `GeneralError` (0)          | Server error.                                         |

## Try it

## POST /GetCustomerById

> Get customer by ID

```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":{"/GetCustomerById":{"post":{"tags":["Customers"],"operationId":"GetCustomerById","summary":"Get customer by ID","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["custId","token"],"properties":{"custId":{"type":"integer"},"token":{"type":"string"}}}}}},"responses":{"200":{"description":"The customer.","content":{"application/json":{"schema":{"type":"object","properties":{"GetCustomerByIdResult":{"$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}}}}}}
```

## POST /GetCustomersByOrgId

> List all customers

```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":{"/GetCustomersByOrgId":{"post":{"tags":["Customers"],"operationId":"GetCustomersByOrgId","summary":"List all customers","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string"}}}}}},"responses":{"200":{"description":"All customers in the organization.","content":{"application/json":{"schema":{"type":"object","properties":{"GetCustomersByOrgIdResult":{"$ref":"#/components/schemas/CustomerCollection"}}}}}}}}}},"components":{"schemas":{"CustomerCollection":{"allOf":[{"$ref":"#/components/schemas/CommonObject"},{"type":"object","properties":{"Response":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/Customer"}}}}]},"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}}},"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}}}]},"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}}}}}}
```

## Search customers

> Filtered search. Populate any subset of Customer fields as the filter.

```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":{"/GetCustomers":{"post":{"tags":["Customers"],"operationId":"GetCustomers","summary":"Search customers","description":"Filtered search. Populate any subset of Customer fields as the filter.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cust","token"],"properties":{"cust":{"$ref":"#/components/schemas/Customer"},"token":{"type":"string"}}}}}},"responses":{"200":{"description":"Matching customers.","content":{"application/json":{"schema":{"type":"object","properties":{"GetCustomersResult":{"$ref":"#/components/schemas/CustomerCollection"}}}}}}}}}},"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}}},"CustomerCollection":{"allOf":[{"$ref":"#/components/schemas/CommonObject"},{"type":"object","properties":{"Response":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/Customer"}}}}]}}}}
```