# 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"}}}}}}}}}
```


---

# 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.gurupay.eu/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.