# Customers

The Customers API allows you to retrieve customer records linked to your integration via two endpoints:

* One for retrieving details for a specific customer.
* One for retrieving a paginated list of customers.

{% hint style="warning" %}
You must include your **Bearer token** in the request header.
{% endhint %}

## Retrieve a paginated list of customers

> Returns a list of customers, paginated according to the 'per\_page' and 'page' query parameters.

```json
{"openapi":"3.0.0","info":{"title":"GURUPAY API","version":"0.2.0"},"tags":[{"name":"Customers","description":"Services intended to work with customer data."}],"servers":[{"url":"https://public-api.gurupay.eu","description":"Production API Server"},{"url":"https://public-api-dev.gurupay.eu","description":"Sandbox API Server"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","description":"Authentication using a Bearer token.","name":"Authorization","in":"header","bearerFormat":"JWT","scheme":"bearer"}},"schemas":{"perPage":{"description":"Number of items to return per page in a paginated response.","type":"integer","default":15,"maximum":100,"minimum":1},"page":{"description":"The current page number for paginated results.","type":"integer","default":1,"minimum":1},"API.Resources.CustomerResource":{"properties":{"uuid":{"description":"The customer's unique identifier.","type":"string","format":"uuid"},"identity_uuid":{"description":"The unique identifier of the associated identity","type":"string","format":"uuid"},"type":{"description":"The category of customer (e.g., individual, company).","type":"string","enum":["individual","company"]},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"created_at":{"$ref":"#/components/schemas/Timestamp"},"name":{"description":"The full name of the customer.","type":"string","maxLength":255},"risk_country_code":{"description":"The country code indicating the customer's risk level. **Not used**","type":"null"},"registration_country_code":{"description":"The country code where the company is officially registered.","type":"string","maxLength":2,"nullable":true},"registration_address_line":{"description":"The main street address for the company's official registration.","type":"string","maxLength":255,"nullable":true},"registration_address_index":{"description":"The postal code or zip code for the company's official registration address.","type":"string","maxLength":20,"nullable":true},"post_address_country_code":{"description":"The country code where the company is physically located.","type":"string","maxLength":2,"nullable":true},"post_address_line":{"description":"The main street address for the company's physical location.","type":"string","maxLength":255,"nullable":true},"post_address_index":{"description":"The postal code or zip code for the company's physical location.","type":"string","maxLength":20,"nullable":true},"related_persons":{"description":"Information about individuals associated with this customer. **Not used**","type":"null"}},"type":"object"},"Timestamp":{"description":"A Unix timestamp in seconds.","type":"integer","format":"int64"},"UnauthenticatedResponse":{"properties":{"status":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}},"type":"object"}}},"paths":{"/api/v1/customers":{"get":{"tags":["Customers"],"summary":"Retrieve a paginated list of customers","description":"Returns a list of customers, paginated according to the 'per_page' and 'page' query parameters.","operationId":"API.Customers.Get","parameters":[{"parameter":"per_page","name":"per_page","in":"query","description":"Number of items to return per page","schema":{"$ref":"#/components/schemas/perPage"}},{"parameter":"page","name":"page","in":"query","description":"The page number to retrieve","schema":{"$ref":"#/components/schemas/page"}}],"responses":{"200":{"description":"A paginated array of customer resources","headers":{"X-RateLimit-Limit":{"description":"The maximum number of requests allowed per minute.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"The number of requests remaining in the current window.","schema":{"type":"integer"}},"X-Api-Total":{"description":"Total number of records matching the filter criteria.","schema":{"type":"integer"}},"X-Api-Per-Page":{"description":"Number of records returned on the current page.","schema":{"type":"integer"}},"X-Api-Has-More-Pages":{"description":"Indicates if there are more pages available.","schema":{"type":"boolean"}},"X-Api-Has-Has-Page":{"description":"The current page number being returned.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/API.Resources.CustomerResource"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}}}}}}}
```

## Retrieve details for a specific customer

> Returns comprehensive information about a customer identified by their unique UUID.

```json
{"openapi":"3.0.0","info":{"title":"GURUPAY API","version":"0.2.0"},"tags":[{"name":"Customers","description":"Services intended to work with customer data."}],"servers":[{"url":"https://public-api.gurupay.eu","description":"Production API Server"},{"url":"https://public-api-dev.gurupay.eu","description":"Sandbox API Server"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","description":"Authentication using a Bearer token.","name":"Authorization","in":"header","bearerFormat":"JWT","scheme":"bearer"}},"schemas":{"UUID":{"description":"Universally Unique Identifier (UUID) as defined by RFC 4122.","type":"string","format":"uuid","pattern":"^[a-zA-Z0-9]{8}-[a-zA-Z0-9]{4}-[a-zA-Z0-9]{4}-[a-zA-Z0-9]{4}-[a-zA-Z0-9]{12}$"},"API.Resources.CustomerResource":{"properties":{"uuid":{"description":"The customer's unique identifier.","type":"string","format":"uuid"},"identity_uuid":{"description":"The unique identifier of the associated identity","type":"string","format":"uuid"},"type":{"description":"The category of customer (e.g., individual, company).","type":"string","enum":["individual","company"]},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"created_at":{"$ref":"#/components/schemas/Timestamp"},"name":{"description":"The full name of the customer.","type":"string","maxLength":255},"risk_country_code":{"description":"The country code indicating the customer's risk level. **Not used**","type":"null"},"registration_country_code":{"description":"The country code where the company is officially registered.","type":"string","maxLength":2,"nullable":true},"registration_address_line":{"description":"The main street address for the company's official registration.","type":"string","maxLength":255,"nullable":true},"registration_address_index":{"description":"The postal code or zip code for the company's official registration address.","type":"string","maxLength":20,"nullable":true},"post_address_country_code":{"description":"The country code where the company is physically located.","type":"string","maxLength":2,"nullable":true},"post_address_line":{"description":"The main street address for the company's physical location.","type":"string","maxLength":255,"nullable":true},"post_address_index":{"description":"The postal code or zip code for the company's physical location.","type":"string","maxLength":20,"nullable":true},"related_persons":{"description":"Information about individuals associated with this customer. **Not used**","type":"null"}},"type":"object"},"Timestamp":{"description":"A Unix timestamp in seconds.","type":"integer","format":"int64"},"UnauthenticatedResponse":{"properties":{"status":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}},"type":"object"},"NotFoundResponse":{"properties":{"status":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}},"type":"object"}}},"paths":{"/api/v1/customers/{uuid}":{"get":{"tags":["Customers"],"summary":"Retrieve details for a specific customer","description":"Returns comprehensive information about a customer identified by their unique UUID.","operationId":"API.Customers.Show","parameters":[{"parameter":"uuid","name":"uuid","in":"path","description":"The unique identifier (UUID) of the customer to retrieve.","required":true,"schema":{"$ref":"#/components/schemas/UUID"}}],"responses":{"200":{"description":"Detailed information about the requested customer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/API.Resources.CustomerResource"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundResponse"}}}}}}}}}
```