# Customers

The data model for customer is represented by [`Customer`](/data-models.md#customer) class.

## API methods

## Get customers

<mark style="color:blue;">`GET`</mark> `http://{server-address}/customers`

Returns all customers that matches query parameters. Result is of type [`QueryResult<Customer>`](/data-models.md#queryresult).

#### Query Parameters

| Name             | Type      | Description                                                                                                                                                          |
| ---------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| CardSerialNumber | string    | Supports NData syntax. Compares `SerialNumber` property of elements in `Cards` collection.                                                                           |
| ExternalId       | string    | Supports NData syntax.                                                                                                                                               |
| CreditRate       | decimal   | Supports NData syntax.                                                                                                                                               |
| DiscountRate     | decimal   | Supports NData syntax.                                                                                                                                               |
| IsActive         | bool      | Supports NData syntax.                                                                                                                                               |
| ExpirationTime   | DateTime  | Supports NData syntax.                                                                                                                                               |
| IsExpired        | bool      | Boolean values allowed. Compares provided value to `Status` property based on `ActivationTime` and `ExpirationTime`.                                                 |
| Search           | string    | Value is compared with partial case-insensitive match in following properties: `FirstName`, `LastName`, `Company.Name`, `Company.VatId`, `Company.TaxId` and `Note`. |
| $skip            | int       | Pagination property. Describing number of records to skip from beginning of result collection.                                                                       |
| $take            | int       | Pagination property. Maximum count of items to be returned.                                                                                                          |
| $sort            | string\[] | <p>Comma separated list of property names. Please see NData syntax.<br></p>                                                                                          |
| $count           | bool      | If set to `true`, response will not contain `items` collection. Use to get resource count, not the resources themselves.                                             |

#### Headers

| Name                                            | Type   | Description                                    |
| ----------------------------------------------- | ------ | ---------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Authorization header with authorization token. |

{% tabs %}
{% tab title="200: OK Successful response" %}

```javascript
{
    "items":
    [
        {
            "id": "customer-id",
            "externalId": null,
            "isActive": true,
            "status": "Valid",
            "activationTime": null,
            "expirationTime": null,
            "firstName": "John",
            "lastName": "Doe",
            "fullName": "John Doe",
            "gender": null,
            "birthDate": null,
            "email": "john.doe@portos.sk",
            "phone": null,
            "isCompany": false,
            "company": null,
            "address": null,
            "deliveryAddress": null,
            "credit":
            {
                "amount": 0.0,
                "currencyLabel": null
            },
            "creditTransactions": [],
            "cards":
            [
                {
                    "externalId": "external-card-id",
                    "isActive": true,
                    "isVirtual": true,
                    "serialNumber": "card-serial-number",
                    "processor": "P",
                    "status": "Valid",
                    "statusTime": null,
                    "statusReason": null,
                    "activationTime": "2022-11-01T00:00:00.00Z",
                    "expirationTime": null,
                    "note": null,
                    "meta": null
                }
            ],
            "creditRate": 0.0,
            "discountRate": 0.0,
            "note": null,
            "meta": {},
            "_v": 1
        }
    ],
    "count": 1,
    "totalCount": 1
}
```

{% endtab %}
{% endtabs %}

## Get customer by ID

<mark style="color:blue;">`GET`</mark> `http://{server-address}/customers/{id}`

Result is of type [`Customer`](#customer).

#### Path Parameters

| Name                                 | Type   | Description                 |
| ------------------------------------ | ------ | --------------------------- |
| id<mark style="color:red;">\*</mark> | string | Unique customer identifier. |

#### Headers

| Name                                            | Type   | Description                                    |
| ----------------------------------------------- | ------ | ---------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Authorization header with authorization token. |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "id": "customer-id",
    "externalId": null,
    "isActive": true,
    "status": "Valid",
    "activationTime": null,
    "expirationTime": null,
    "firstName": "John",
    "lastName": "Doe",
    "fullName": "John Doe",
    "gender": null,
    "birthDate": null,
    "email": "john.doe@portos.sk",
    "phone": null,
    "isCompany": false,
    "company": null,
    "address": null,
    "deliveryAddress": null,
    "credit":
    {
        "amount": 0.0,
        "currencyLabel": null
    },
    "creditTransactions":
    [],
    "cards":
    [
        {
            "externalId": "external-card-id",
            "isActive": true,
            "isVirtual": true,
            "serialNumber": "card-serial-number",
            "processor": "P",
            "status": "Valid",
            "statusTime": null,
            "statusReason": null,
            "activationTime": "2022-11-01T00:00:00.00Z",
            "expirationTime": null,
            "note": null,
            "meta": null
        }
    ],
    "creditRate": 0.0,
    "discountRate": 0.0,
    "note": null,
    "meta":
    {},
    "_v": 1
}
```

{% endtab %}

{% tab title="404: Not Found Customer with given ID is not found." %}

```javascript
{
    "title": "Zdroj nebol nájdený",
    "status": 404
}
```

{% endtab %}
{% endtabs %}

## Create customer

<mark style="color:green;">`POST`</mark> `http://{server-address}/customers`

Creates new customer. Result is of type [`Customer`](#customer).

**Required rights**

Authorized user must have `CustomerCreate` [right ](/user-rights.md)assigned.

#### Headers

| Name                                            | Type   | Description                                    |
| ----------------------------------------------- | ------ | ---------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Authorization header with authorization token. |

#### Request Body

| Name                                     | Type     | Description              |
| ---------------------------------------- | -------- | ------------------------ |
| (body)<mark style="color:red;">\*</mark> | Customer | Customer model to create |

{% tabs %}
{% tab title="201: Created " %}

```javascript
{
    "id": "customer-id",
    "externalId": null,
    "isActive": true,
    "status": "Valid",
    "activationTime": null,
    "expirationTime": null,
    "firstName": "John",
    "lastName": "Doe",
    "fullName": "John Doe",
    "gender": null,
    "birthDate": null,
    "email": "john.doe@portos.sk",
    "phone": null,
    "isCompany": false,
    "company": null,
    "address": null,
    "deliveryAddress": null,
    "credit":
    {
        "amount": 0.0,
        "currencyLabel": null
    },
    "creditTransactions":
    [],
    "cards":
    [
        {
            "externalId": "external-card-id",
            "isActive": true,
            "isVirtual": true,
            "serialNumber": "card-serial-number",
            "processor": "P",
            "status": "Valid",
            "statusTime": null,
            "statusReason": null,
            "activationTime": "2022-11-01T00:00:00.00Z",
            "expirationTime": null,
            "note": null,
            "meta": null
        }
    ],
    "creditRate": 0.0,
    "discountRate": 0.0,
    "note": null,
    "meta":
    {},
    "_v": 1
}
```

{% endtab %}
{% endtabs %}

## Create or update customer

<mark style="color:orange;">`PUT`</mark> `http://{server-address}/customers/{id}`

Updates existing or creates new customer. Result is of type [`Customer`](#customer).

**Required rights**

Authorized user must have assigned `CustomerCreate` or `CustomerUpdate` [right](/user-rights.md). When updating existing customer, additional roles may be required: if `discountRate` property is changed, `CustomerSetDiscount` is required; If `credit` property is changed, `CustomerSetCredit` is required.

#### Path Parameters

| Name                                 | Type   | Description                 |
| ------------------------------------ | ------ | --------------------------- |
| id<mark style="color:red;">\*</mark> | string | Unique customer identifier. |

#### Headers

| Name                                            | Type   | Description                                    |
| ----------------------------------------------- | ------ | ---------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Authorization header with authorization token. |

#### Request Body

| Name                                     | Type     | Description                         |
| ---------------------------------------- | -------- | ----------------------------------- |
| (body)<mark style="color:red;">\*</mark> | Customer | Customer model to create or update. |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "id": "customer-id",
    "externalId": null,
    "isActive": true,
    "status": "Valid",
    "activationTime": null,
    "expirationTime": null,
    "firstName": "John",
    "lastName": "Doe",
    "fullName": "John Doe",
    "gender": null,
    "birthDate": null,
    "email": "john.doe@portos.sk",
    "phone": null,
    "isCompany": false,
    "company": null,
    "address": null,
    "deliveryAddress": null,
    "credit":
    {
        "amount": 0.0,
        "currencyLabel": null
    },
    "creditTransactions":
    [],
    "cards":
    [
        {
            "externalId": "external-card-id",
            "isActive": true,
            "isVirtual": true,
            "serialNumber": "card-serial-number",
            "processor": "P",
            "status": "Valid",
            "statusTime": null,
            "statusReason": null,
            "activationTime": "2022-11-01T00:00:00.00Z",
            "expirationTime": null,
            "note": null,
            "meta": null
        }
    ],
    "creditRate": 0.0,
    "discountRate": 0.0,
    "note": null,
    "meta":
    {},
    "_v": 1
}
```

{% endtab %}
{% endtabs %}

## Delete customer by ID

<mark style="color:red;">`DELETE`</mark> `http://{server-address}/customers/{id}`

**Required rights**

Authorized user must have `CustomerDelete` [right ](/user-rights.md)assigned.

#### Path Parameters

| Name                                 | Type   | Description                 |
| ------------------------------------ | ------ | --------------------------- |
| id<mark style="color:red;">\*</mark> | string | Unique customer identifier. |

#### Headers

| Name                                            | Type   | Description                                    |
| ----------------------------------------------- | ------ | ---------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Authorization header with authorization token. |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "id": "customer-id",
    "externalId": null,
    "isActive": true,
    "status": "Valid",
    "activationTime": null,
    "expirationTime": null,
    "firstName": "John",
    "lastName": "Doe",
    "fullName": "John Doe",
    "gender": null,
    "birthDate": null,
    "email": "john.doe@portos.sk",
    "phone": null,
    "isCompany": false,
    "company": null,
    "address": null,
    "deliveryAddress": null,
    "credit":
    {
        "amount": 0.0,
        "currencyLabel": null
    },
    "creditTransactions":
    [],
    "cards":
    [
        {
            "externalId": "external-card-id",
            "isActive": true,
            "isVirtual": true,
            "serialNumber": "card-serial-number",
            "processor": "P",
            "status": "Valid",
            "statusTime": null,
            "statusReason": null,
            "activationTime": "2022-11-01T00:00:00.00Z",
            "expirationTime": null,
            "note": null,
            "meta": null
        }
    ],
    "creditRate": 0.0,
    "discountRate": 0.0,
    "note": null,
    "meta":
    {},
    "_v": 1
}
```

{% endtab %}

{% tab title="404: Not Found " %}

```javascript
{
    "title": "Zdroj nebol nájdený",
    "status": 404
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.portos.sk/api-reference/customers.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.