Leat V3 OAuth

https://docs.leat.com/v3/oauth
Admin
Leat V3 OAuth is a comprehensive API platform providing OAuth authentication and integration...
Tokens:36,111
Snippets:75
Trust Score:7.3
Update:11 months ago
Show doc for...
Tokens:
Raw
### Contact Attribute Creation Response Example

Source: https://docs.leat.com/v3/oauth/contact-attributes

This is an example of a successful response when creating a new contact attribute. It details the structure of the returned attribute, including its name, label, type, and options if applicable.

```json
{
  "data": {
    "name": "favorite_color",
    "label": "Your Favorite Color",
    "description": "some description",
    "type": "select",
    "field_type": "select",
    "is_soft_read_only": false,
    "is_hard_read_only": false,
    "is_piggy_defined": false,
    "options": [
      {
        "label": "Blue",
        "value": "blue"
      },
      {
        "label": "Red",
        "value": "red"
      },
      {
        "label": "Yellow",
        "value": "yellow"
      }
    ]
  },
  "meta": {}
}
```

--------------------------------

### List Rewards Response Example (JSON)

Source: https://docs.leat.com/v3/oauth/rewards

An example of the JSON response when listing available rewards via the OAuth API. It demonstrates the structure of the 'data' array, containing individual reward objects with properties like 'id', 'uuid', 'title', 'type', 'required_credits', and 'media'.

```json
{
  "data": [
    {
      "id": 1,
      "uuid": "6bfe1e50-b13a-49ab-85c9-98cd8b734da2",
      "title": "Donation to charity",
      "type": "DIGITAL",
      "is_active": true,
      "reward_type": "DIGITAL",
      "description": "Helping people",
      "required_credits": 25,
      "media": {
        "type": "image",
        "value": "https://images.unsplash.com/photo-1565945887714-d5139f4eb0ce"
      },
      "custom_attribute_one": "ABC",
      "custom_attribute_two": "123"
    },
    {
      "id": 2,
      "uuid": "bcd51b4b-88be-4a5d-b658-0e59dc1dabbc",
      "title": "Cup of coffee",
      "type": "PHYSICAL",
      "is_active": true,
      "reward_type": "PHYSICAL",
      "description": "Choice between lungo, espresso or cappuccino",
      "required_credits": 50,
      "media": {
        "type": "image",
        "value": "https://images.unsplash.com/photo-1565945887714-d5139f4eb0ce"
      },
      "custom_attribute_one": "DEF",
      "custom_attribute_two": "456",
      "pre_redeemable": false,
      "expiration_duration": null
    }
  ],
  "meta": {}
}
```

--------------------------------

### Get Specific Reward by UUID (GET)

Source: https://docs.leat.com/v3/oauth/rewards

Retrieves detailed information about a specific reward using its unique identifier (UUID). This operation requires an access token and specifies the reward's UUID as a path parameter. It returns the reward's data, including its properties and associated media.

```http
GET https://api.leat.com/api/v3/oauth/clients/rewards/{{reward_uuid}}

Headers:
Authorization: Bearer {{ access_token | api_key }}
Accept: application/json

Params:
reward_uuid (string, REQUIRED): The UUID of the Reward to retrieve.
```

--------------------------------

### GET /api/v3/oauth/clients/credit-receptions/calculate

Source: https://docs.leat.com/v3/oauth/credit-receptions

Calculates the number of credits that would be issued for a potential Credit Reception without actually creating it.

```APIDOC
## GET /api/v3/oauth/clients/credit-receptions/calculate

### Description
This endpoint allows you to calculate the potential number of credits that would be issued for a Credit Reception based on provided values, without creating the reception itself. Be aware that time-based loyalty rules might cause slight divergences between the calculated and actual credits.

### Method
GET

### Endpoint
`https://api.leat.com/api/v3/oauth/clients/credit-receptions/calculate`

### Parameters
#### Query Parameters
- **shop_uuid** (string) - REQUIRED - The UUID of the Shop for which the credits are to be calculated.
- **contact_uuid** (string) - OPTIONAL - The UUID of the Contact for whom the credits are to be calculated.
- **unit_value** (number) - REQUIRED - The value for which credits are to be calculated. This is subject to Loyalty Rules.
- **unit_name** (string) - OPTIONAL - The name of the unit for the `unit_value`. If neither `unit_name` nor `credits` are provided, the default unit (`purchase_amount`) is used.

#### Headers
- **Authorization** (string) - REQUIRED - Bearer token for authentication (`Bearer {{ access_token | api_key }}`).
- **Accept** (string) - REQUIRED - Specifies the expected response format (`application/json`).

### Response
#### Success Response (200)
- **data** (object) - Contains the calculated credits.
  - **credits** (integer) - The calculated number of credits.
- **meta** (object) - Metadata associated with the response.

#### Response Example
```json
{
  "data": {
    "credits": 10240
  },
  "meta": {}
}
```

#### Possible Errors
- **1003**: Invalid input.
- **1008**: Shop not found.
- **55031**: Contact not found.
- **60007**: Unit not found.

```

--------------------------------

### Find or Create Contact Async - Response Example

Source: https://docs.leat.com/v3/oauth/contacts

The response from the 'Find or Create Contact Async' endpoint contains a 'data' object with the 'uuid' of the found or newly created contact. This provides a quick identifier for subsequent operations.

```JSON
{
  "data": {
    "uuid": "cd183615-d1cb-402a-b618-6472d5e13890"
  },
  "meta": []
}
```

--------------------------------

### GET /api/v3/oauth/clients/rewards

Source: https://docs.leat.com/v3/oauth/rewards

Lists rewards available for a specific shop or claimable by a specific contact. This endpoint is crucial for displaying available rewards in-store or allowing users to see and potentially redeem rewards.

```APIDOC
## GET /api/v3/oauth/clients/rewards

### Description
This API endpoint is used to list Rewards available for to be shown in-store or to list Rewards that a specific Contact can claim, with potentially a subsequent Create Reward Reception call when a Contact claims a Reward. The list of Rewards for a particular Contact might differ from the full list of Rewards.

### Method
GET

### Endpoint
`https://api.leat.com/api/v3/oauth/clients/rewards`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **shop_uuid** (string) - Optional - The Shop UUID for which the Rewards you want to retrieve.
- **contact_uuid** (string) - Optional - List the claimable rewards associated with the Contact by supplying their UUID.

#### Headers
- **Authorization** (string) - Required - `Bearer {{ access_token | api_key }}`
- **Accept** (string) - Required - `application/json`

### Request Example
None provided

### Response
#### Success Response (200)
- **data** (array) - An array of reward objects.
  - **id** (integer) - The unique identifier for the reward.
  - **uuid** (string) - The universally unique identifier for the reward.
  - **title** (string) - The title or name of the reward.
  - **type** (string) - The type of reward (e.g., "DIGITAL", "PHYSICAL").
  - **is_active** (boolean) - Indicates if the reward is currently active.
  - **reward_type** (string) - The type of reward (e.g., "DIGITAL", "PHYSICAL").
  - **description** (string) - A description of the reward.
  - **required_credits** (integer) - The number of credits required to redeem the reward.
  - **media** (object) - Information about the reward's media.
    - **type** (string) - The type of media (e.g., "image").
    - **value** (string) - The URL or value of the media.
  - **custom_attribute_one** (string) - A custom attribute for the reward.
  - **custom_attribute_two** (string) - Another custom attribute for the reward.
  - **pre_redeemable** (boolean) - Indicates if the reward can be redeemed before reaching the required credits.
  - **expiration_duration** (integer) - The duration in seconds for which the reward is valid after redemption.
- **meta** (object) - Metadata associated with the response.

#### Response Example
```json
{
  "data": [
    {
      "id": 1,
      "uuid": "6bfe1e50-b13a-49ab-85c9-98cd8b734da2",
      "title": "Donation to charity",
      "type": "DIGITAL",
      "is_active": true,
      "reward_type": "DIGITAL",
      "description": "Helping people",
      "required_credits": 25,
      "media": {
        "type": "image",
        "value": "https://images.unsplash.com/photo-1565945887714-d5139f4eb0ce"
      },
      "custom_attribute_one": "ABC",
      "custom_attribute_two": "123"
    },
    {
      "id": 2,
      "uuid": "bcd51b4b-88be-4a5d-b658-0e59dc1dabbc",
      "title": "Cup of coffee",
      "type": "PHYSICAL",
      "is_active": true,
      "reward_type": "PHYSICAL",
      "description": "Choice between lungo, espresso or cappuccino",
      "required_credits": 50,
      "media": {
        "type": "image",
        "value": "https://images.unsplash.com/photo-1565945887714-d5139f4eb0ce"
      },
      "custom_attribute_one": "DEF",
      "custom_attribute_two": "456",
      "pre_redeemable": false,
      "expiration_duration": null
    }
  ],
  "meta": {}
}
```

### Error Handling
- **1008**: Shop not found.
- **55031**: Contact not found.
```

--------------------------------

### POST /api/v3/oauth/clients/credit-receptions

Source: https://docs.leat.com/v3/oauth/credit-receptions

Creates a credit reception for a given shop and contact. You can either specify the number of credits directly or provide a unit value and name. Loyalty rules can influence the credit calculation if only unit value and name are provided.

```APIDOC
## POST /api/v3/oauth/clients/credit-receptions

### Description
Creates a credit reception, which can be used to award credits to a contact. You can specify the number of `credits` directly, or provide a `unit_value` and `unit_name`. If only `unit_value` and `unit_name` are provided, Loyalty Rules may influence the final credit amount. It is recommended to use `unit_name` and `unit_value` to mimic in-store behavior. If `unit_name` is omitted, the default unit (`purchase_amount`) will be used. `credits` should be set explicitly if the reception does not concern a transaction or if a partial refund is needed.

### Method
POST

### Endpoint
`https://api.leat.com/api/v3/oauth/clients/credit-receptions`

### Parameters
#### Headers
- **Authorization** (string) - Required - `Bearer {{ access_token | api_key }}`
- **Accept** (string) - Required - `application/json`

#### Request Body
- **shop_uuid** (string) - Required - The UUID of the Shop you want to create the Credit Reception for.
- **contact_uuid** (string) - Required - The UUID of the Contact for whom the Credit Reception is to be created.
- **credits** (number) - Required if `unit_value` is not set - Number of Credits. Overrides any Loyalty Rules.
- **unit_value** (number) - Required if `credits` is not set - Value of the Unit to be given. Subject to any Loyalty Rules. Use a float for values like currency (e.g., 10.40).
- **unit_name** (string) - Optional - Name of the Unit for the corresponding value. If both `unit_name` and `credits` are not set, the default unit (`purchase_amount`) is used.
- **contact_identifier_value** (string) - Optional - The value of the Contact Identifier linked to the Contact.
- **pos_transaction_uuid** (string) - Optional - The UUID of the POS transaction to link the Credit Reception to.

### Request Example
```json
{
  "shop_uuid": "your_shop_uuid",
  "contact_uuid": "your_contact_uuid",
  "unit_value": 10.50,
  "unit_name": "EUR",
  "contact_identifier_value": "customer_id_123",
  "pos_transaction_uuid": "your_pos_transaction_uuid"
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains the details of the created credit reception.
  - **data.type** (string) - The type of the resource (e.g., "credit_reception").
  - **data.contact_identifier** (any) - Information about the contact identifier.
  - **data.contact** (object) - Details of the contact.
    - **data.contact.uuid** (string) - The UUID of the contact.
    - **data.contact.email** (string) - The email of the contact.
    - **data.contact.credit_balance** (object) - The current credit balance of the contact.
      - **data.contact.credit_balance.id** (number) - The ID of the credit balance entry.
      - **data.contact.credit_balance.balance** (number) - The current credit balance.
  - **data.shop** (object) - Details of the shop.
    - **data.shop.id** (number) - The ID of the shop.
    - **data.shop.uuid** (string) - The UUID of the shop.
    - **data.shop.type** (string) - The type of the shop (e.g., "physical").
    - **data.shop.name** (string) - The name of the shop.
    - **data.shop.address** (object) - The address of the shop.
      - **data.shop.address.id** (number) - The ID of the address.
      - **data.shop.address.shop_id** (number) - The ID of the shop the address belongs to.
      - **data.shop.address.street** (string) - The street name.
      - **data.shop.address.housenumber** (number) - The house number.
      - **data.shop.address.postalcode** (string) - The postal code.
      - **data.shop.address.city** (string) - The city.
      - **data.shop.address.state** (string) - The state or province.
      - **data.shop.address.country** (string) - The country code.
      - **data.shop.address.latitude** (any) - Latitude coordinate (nullable).
      - **data.shop.address.longitude** (any) - Longitude coordinate (nullable).
  - **data.credits** (number) - The number of credits awarded.
  - **data.created_at** (string) - The timestamp when the credit reception was created.
  - **data.uuid** (string) - The UUID of the credit reception.
  - **data.unit** (object) - Details about the unit used for the credit reception.
    - **data.unit.id** (number) - The ID of the unit.
    - **data.unit.name** (string) - The name of the unit.
    - **data.unit.label** (string) - The label for the unit.
    - **data.unit.prefix** (string) - Prefix for the unit.
    - **data.unit.is_default** (boolean) - Indicates if this is the default unit.
  - **data.unit_value** (any) - The value of the unit, if applicable (nullable).
  - **data.someAttribute** (any) - Placeholder for potential additional attributes.
  - **data.someAttribute2** (any) - Placeholder for potential additional attributes.
  - **data.someAttribute21123** (any) - Placeholder for potential additional attributes.
- **meta** (object) - Contains metadata about the response.

#### Response Example
```json
{
  "data": {
    "type": "credit_reception",
    "contact_identifier": null,
    "contact": {
      "uuid": "123",
      "email": "john@doe.com",
      "credit_balance": {
        "id": 2625740,
        "balance": 1642
      }
    },
    "shop": {
      "id": 15,
      "uuid": "123123",
      "type": "physical",
      "name": "Amsterdam Pop-up Store",
      "address": {
        "id": 59,
        "shop_id": 15,
        "street": "Sesame Street",
        "housenumber": 12,
        "postalcode": "9999YZ",
        "city": "Duckburg",
        "state": "NH",
        "country": "NL",
        "latitude": null,
        "longitude": null,
        "house_number": null,
        "postal_code": null
      }
    },
    "credits": 10,
    "created_at": "2023-11-06T09:12:32+00:00",
    "uuid": "294183c2-20f2-4f86-a5e5-17e71c4b0660",
    "unit": {
      "id": 112,
      "name": "test",
      "label": "Calories",
      "prefix": "",
      "is_default": true
    },
    "unit_value": null,
    "someAttribute": null,
    "someAttribute2": null,
    "someAttribute21123": null
  },
  "meta": {}
}
```

### Possible errors
- **1003**: Invalid input.
- **1008**: Shop not found.
- **55031**: Contact not found.
- **60003**: Contact identifier not found.
- **60007**: Unit not found.
- **1015**: Maximum amount of credits reached.
- **60001**: Credit reception creating in progress.
- **55046**: No default unit found.
- **1027**: POS Transaction not found.
- **6001**: The POS transaction is already linked to a credit reception.
```

--------------------------------

### Find or Create Contact Async

Source: https://docs.leat.com/v3/oauth/contacts

This endpoint allows for the quick retrieval or creation of a contact. It is optimized for speed when only the contact's UUID is needed.

```APIDOC
## GET /api/v3/oauth/clients/contacts/find-or-create/async

### Description
If a Contact needs to be retrieved or created _quickly_ and any system values that are normally created upon contact creation aren't relevant, this can be used. This API call is much faster than the 'regular' find or create API call; only the Contact's UUID will be returned on the response in this instance.

### Method
GET

### Endpoint
`https://api.leat.com/api/v3/oauth/clients/contacts/find-or-create/async`

### Headers
- **Authorization** (string) - `Bearer {{ access_token | api_key }}`
- **Accept** (string) - `application/json`

### Query Parameters
- **email** (string) - Required - The email address of the Contact to be created or to be found.

### Response
#### Success Response (200)
- **data.uuid** (string) - The unique identifier of the contact.

#### Response Example
```json
{
  "data": {
    "uuid": "cd183615-d1cb-402a-b618-6472d5e13890"
  },
  "meta": []
}
```

### Errors
- **1003** - Invalid input.
- **60000** - Usage limit reached.
```

--------------------------------

### Get Contact

Source: https://docs.leat.com/v3/oauth/contacts

Retrieves a specific contact using its UUID. Requires an authorization token.

```APIDOC
## GET /api/v3/oauth/clients/contacts/{{contact_uuid}}

### Description
Retrieve a specific Contact using its UUID.

### Method
GET

### Endpoint
`https://api.leat.com/api/v3/oauth/clients/contacts/{{contact_uuid}}`

### Parameters
#### Path Parameters
- **contact_uuid** (string) - REQUIRED - The Contact's UUID

#### Headers
- **Authorization** (string) - REQUIRED - `Bearer {{ access_token | api_key }}`
- **Accept** (string) - REQUIRED - `application/json`

### Response
#### Success Response (200)
- **data** (object) - Contains the contact details.
  - **id** (integer) - The contact's ID.
  - **uuid** (string) - The contact's UUID.
  - **email** (string) - The contact's email address.
  - **attributes** (array) - A list of attributes associated with the contact.
    - **value** (string) - The value of the attribute.
    - **attribute** (object) - Details about the attribute.
      - **id** (integer) - The attribute's ID.
      - **type** (string) - The attribute's type.
      - **field_type** (string) - The attribute's field type.
      - **name** (string) - The attribute's name.
      - **label** (string) - The attribute's label.
      - **options** (array) - Options for the attribute.
      - **is_piggy_defined** (boolean) - Indicates if the attribute is defined in piggy.
      - **is_soft_read_only** (boolean) - Indicates if the attribute is soft read-only.
      - **is_hard_read_only** (boolean) - Indicates if the attribute is hard read-only.

#### Response Example
```json
{
  "data": {
    "id": 22,
    "uuid": "123",
    "email": "john@doe.com",
    "attributes": [
      {
        "value": "",
        "attribute": {
          "id": 2204,
          "type": "media_upload",
          "field_type": "media_upload",
          "name": "avatar",
          "label": "Avatar",
          "options": [],
          "is_piggy_defined": true,
          "is_soft_read_only": false,
          "is_hard_read_only": false
        }
      },
      {
        "value": "",
        "attribute": {
          "id": 2205,
          "type": "text",
          "field_type": "text",
          "name": "firstname",
          "label": "First name",
          "options": [],
          "is_piggy_defined": true,
          "is_soft_read_only": false,
          "is_hard_read_only": false
        }
      },
      {
        "value": "",
        "attribute": {
          "id": 2206,
          "type": "text",
          "field_type": "text",
          "name": "lastname",
          "label": "Last name",
          "options": [],
          "is_piggy_defined": true,
          "is_soft_read_only": false,
          "is_hard_read_only": false
        }
      },
      {
        "value": "john@doe.com",
        "attribute": {
          "id": 2203,
          "type": "email",
          "field_type": "email",
          "name": "email",
          "label": "Email",
          "options": [],
          "is_piggy_defined": true,
          "is_soft_read_only": true,
          "is_hard_read_only": true
        }
      },
      {
        "value": "1617",
        "attribute": {
          "id": 2220,
          "type": "number",
          "field_type": "number",
          "name": "previous_loyalty_balance",
          "label": "Previous credit balance",
          "options": [],
          "is_piggy_defined": true,
          "is_soft_read_only": true,
          "is_hard_read_only": false
        }
      },
      {
        "value": "1612",
        "attribute": {
          "id": 2219,
          "type": "number",
          "field_type": "number",
          "name": "loyalty_balance",
          "label": "Credit balance",
          "options": [],
          "is_piggy_defined": true,
          "is_soft_read_only": true,
          "is_hard_read_only": false
        }
      },
      {
        "value": "55",
        "attribute": {
          "id": 2223,
          "type": "number",
          "field_type": "number",
          "name": "loyalty_number_of_transactions",
          "label": "N"
        }
      }
    ]
  }
}
```
```

--------------------------------

### POST /api/v3/oauth/clients/contact-attributes

Source: https://docs.leat.com/v3/oauth/contact-attributes

Create a custom Contact Attribute. After the request, you get the created attribute as a response.

```APIDOC
## POST /api/v3/oauth/clients/contact-attributes

### Description
This method allows you to create your own custom Contact Attribute. After the request, you get the created attribute as a response.

### Method
POST

### Endpoint
`https://api.leat.com/api/v3/oauth/clients/contact-attributes`

### Headers
- **Authorization** (string) - `Bearer {{ access_token | api_key }}`
- **Accept** (string) - `application/json`

### Parameters
#### Request Body
- **name** (string) - Required - The unique value for the Contact Attribute, used for internal purposes.
- **label** (string) - Optional - The label for the attribute, which is outputted.
- **data_type** (string) - Required - The data type of the attribute, possible options: url, text, date, phone, float, color, email, number, select, boolean, rich_text, date_time, long_text, date_range, time_range, identifier, birth_date, file_upload, media_upload, multi_select or license_plate.
- **description** (string) - Optional - A description for the attribute.
- **options** (array) - Optional - Applicable for (multi)selects only. Array consisting of label and value arrays.

### Request Example
```json
{
  "name": "favorite_color",
  "label": "Your Favorite Color",
  "description": "some description",
  "type": "select",
  "field_type": "select",
  "is_soft_read_only": false,
  "is_hard_read_only": false,
  "is_piggy_defined": false,
  "options": [
    {
      "label": "Blue",
      "value": "blue"
    },
    {
      "label": "Red",
      "value": "red"
    },
    {
      "label": "Yellow",
      "value": "yellow"
    }
  ]
}
```

### Response
#### Success Response (200)
- **data** (object) - The created contact attribute details.
  - **name** (string) - The name of the attribute.
  - **label** (string) - The label of the attribute.
  - **description** (string) - The description of the attribute.
  - **type** (string) - The data type of the attribute.
  - **field_type** (string) - The field type of the attribute.
  - **is_soft_read_only** (boolean) - Indicates if the attribute is soft read-only.
  - **is_hard_read_only** (boolean) - Indicates if the attribute is hard read-only.
  - **is_piggy_defined** (boolean) - Indicates if the attribute is piggy-defined.
  - **options** (array) - The options for select type attributes.
    - **label** (string) - The label of the option.
    - **value** (string) - The value of the option.
- **meta** (object) - Metadata about the response.

#### Response Example
```json
{
  "data": {
    "name": "favorite_color",
    "label": "Your Favorite Color",
    "description": "some description",
    "type": "select",
    "field_type": "select",
    "is_soft_read_only": false,
    "is_hard_read_only": false,
    "is_piggy_defined": false,
    "options": [
      {
        "label": "Blue",
        "value": "blue"
      },
      {
        "label": "Red",
        "value": "red"
      },
      {
        "label": "Yellow",
        "value": "yellow"
      }
    ]
  },
  "meta": {}
}
```

### Possible errors
- **1003**: Invalid input.
- **60009**: Attribute already exists.
```

--------------------------------

### POST /api/v3/oauth/clients/contacts/async

Source: https://docs.leat.com/v3/oauth/contacts

Creates a contact asynchronously. This is a faster alternative to the standard 'Create Contact' API when system values are not immediately relevant. It focuses on the basic creation of a contact.

```APIDOC
## POST /api/v3/oauth/clients/contacts/async

### Description
Creates a contact asynchronously. This is a faster alternative to the standard 'Create Contact' API when system values are not immediately relevant. It focuses on the basic creation of a contact.

### Method
POST

### Endpoint
`https://api.leat.com/api/v3/oauth/clients/contacts/async`

### Headers
- **Authorization** (`Bearer {{ access_token | api_key }}`)
- **Accept** (`application/json`)

### Parameters
#### Request Body
- **email** (string) - REQUIRED - The email address of the Contact to be created.
- **referral_code** (string) - OPTIONAL - A referral code used for Piggy's referral programme.

### Request Example
```json
{
  "email": "string",
  "referral_code": "string"
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains the uuid of the newly created contact.
  - **uuid** (string) - The unique identifier for the created contact.
- **meta** (array) - An empty array for metadata.

#### Response Example
```json
{
  "data": {
    "uuid": "cd183615-d1cb-402a-b618-6472d5e13890"
  },
  "meta": []
}
```

### Possible errors
- **1003**: Invalid input.
- **60005**: Contact already exists.
- **60000**: Usage limit reached.
```

--------------------------------

### GET /api/v3/oauth/clients/contacts/{contact_uuid}/credit-balance

Source: https://docs.leat.com/v3/oauth/contacts

Retrieves the current credit balance for a specified Contact using their UUID.

```APIDOC
## GET /api/v3/oauth/clients/contacts/{contact_uuid}/credit-balance

### Description
Retrieves the current Credit Balance of a specific Contact, identified through their UUID. This is useful for understanding a contact's available credits.

### Method
GET

### Endpoint
`https://api.leat.com/api/v3/oauth/clients/contacts/{{contact_uuid}}/credit-balance`

### Parameters
#### Headers
- **Authorization** (string) - Required - `Bearer {{ access_token | api_key }}`
- **Accept** (string) - Required - `application/json`

#### Query Parameters
- **contact_uuid** (string) - Required - The Contact's UUID.

### Response
#### Success Response (200)
- **data** (object) - Object containing the credit balance.
  - **balance** (integer) - The current credit balance.
- **meta** (array) - Metadata associated with the response.

#### Response Example
```json
{
  "data": {
    "balance": 49
  },
  "meta": []
}
```

#### Error Response
- **1003**: Invalid input.
- **55031**: Contact not found.
```

--------------------------------

### Credit Receptions API

Source: https://docs.leat.com/v3/oauth/credit-receptions

Endpoints for managing credit receptions, including creating and reversing them. Credit receptions are fundamental to collecting credits in the Piggy Loyalty system.

```APIDOC
## Credit Receptions

Credit Receptions are the backbone of the Piggy Loyalty system. It lets our end-users collect credits and it's therefore the basis for virtually every loyalty integration. Before starting to build your integration, we ask you read the recommended flows.

### Refunds and reversing Credit Receptions

At times, initially issued credits need to be reverted, when an order was refunded for instance. In such a case, it's important to note that creating a Credit Reception with a negative `unit_value` is inadvisable. Due to the possibility of Loyalty Rules dependent on variables (e.g. time-based filters or Tier-based filters) being present, the resulting number of credits issued can differ from the initial transaction to be corrected.
**Instead, use the `Reverse Credit Reception` API call to reverse an initial transaction.**

#### Partial refunds

In case of partial refunds, it gets a bit more tricky. To account for time-based and attribute-based filters as best as possible, we recommend to calculate the percentage of the order that was refunded, take that percentage of the _credits_ initially issued, and create a Credit Reception with that negative amount of `credits` (do _not_ use `unit_value` (e.g. initial transaction of €50.00 issued 80 credits, €20.00 was refunded, so new Credit Reception for -32 credits).

## POST /credit-receptions/reverse

### Description
Reverses an initial credit reception transaction.

### Method
POST

### Endpoint
/credit-receptions/reverse

### Parameters
#### Request Body
- **credit_reception_id** (string) - Required - The ID of the credit reception to reverse.
- **refund_amount** (number) - Optional - The amount to refund. If not provided, the entire credit reception will be reversed.

### Request Example
```json
{
  "credit_reception_id": "cr_12345",
  "refund_amount": 32
}
```

### Response
#### Success Response (200)
- **message** (string) - A success message.

#### Response Example
```json
{
  "message": "Credit reception reversed successfully."
}
```
```

--------------------------------

### Find or Create Contact

Source: https://docs.leat.com/v3/oauth/contacts

Finds an existing contact by email address. If no contact is found, it creates a new contact with the provided email and returns the newly created contact.

```APIDOC
## GET /api/v3/oauth/clients/contacts/find-or-create

### Description
Finds a contact by email. If the contact does not exist, it creates a new contact and returns it.

### Method
GET

### Endpoint
`https://api.leat.com/api/v3/oauth/clients/contacts/find-or-create`

### Headers
- **Authorization** (string) - Required - `Bearer {{ access_token | api_key }}`
- **Accept** (string) - Required - `application/json`

### Query Parameters
- **email** (string) - Required - The Contact's email address.

### Response
#### Success Response (200)
- **data** (object) - Contains the contact information.
  - **id** (integer) - The unique identifier for the contact.
  - **uuid** (string) - The universally unique identifier for the contact.
  - **email** (string) - The email address of the contact.
  - **attributes** (array) - A list of attributes associated with the contact.
    - **value** (string) - The value of the attribute.
    - **attribute** (object) - Details about the attribute.
      - **id** (integer) - The attribute's ID.
      - **type** (string) - The attribute's type.
      - **field_type** (string) - The attribute's field type.
      - **name** (string) - The attribute's name.
      - **label** (string) - The attribute's label.
      - **options** (array) - Options for the attribute (if applicable).
      - **is_piggy_defined** (boolean) - Indicates if the attribute is defined in the piggy system.
      - **is_soft_read_only** (boolean) - Indicates if the attribute is soft read-only.
      - **is_hard_read_only** (boolean) - Indicates if the attribute is hard read-only.

### Response Example
```json
{
  "data": {
    "id": 22,
    "uuid": "123",
    "email": "john@doe.com",
    "attributes": [
      {
        "value": "",
        "attribute": {
          "id": 2204,
          "type": "media_upload",
          "field_type": "media_upload",
          "name": "avatar",
          "label": "Avatar",
          "options": [],
          "is_piggy_defined": true,
          "is_soft_read_only": false,
          "is_hard_read_only": false
        }
      },
      {
        "value": "",
        "attribute": {
          "id": 2205,
          "type": "text",
          "field_type": "text",
          "name": "firstname",
          "label": "First name",
          "options": [],
          "is_piggy_defined": true,
          "is_soft_read_only": false,
          "is_hard_read_only": false
        }
      },
      {
        "value": "",
        "attribute": {
          "id": 2206,
          "type": "text",
          "field_type": "text",
          "name": "lastname",
          "label": "Last name",
          "options": [],
          "is_piggy_defined": true,
          "is_soft_read_only": false,
          "is_hard_read_only": false
        }
      },
      {
        "value": "john@doe.com",
        "attribute": {
          "id": 2203,
          "type": "email",
          "field_type": "email",
          "name": "email",
          "label": "Email",
          "options": [],
          "is_piggy_defined": true,
          "is_soft_read_only": true,
          "is_hard_read_only": true
        }
      },
      {
        "value": "1617",
        "attribute": {
          "id": 2220,
          "type": "number",
          "field_type": "number",
          "name": "previous_loyalty_balance",
          "label": "Previous credit balance",
          "options": [],
          "is_piggy_defined": true,
          "is_soft_read_only": true,
          "is_hard_read_only": false
        }
      },
      {
        "value": "1612",
        "attribute": {
          "id": 2219,
          "type": "number",
          "field_type": "number",
          "name": "loyalty_balance",
          "label": "Credit balance",
          "options": [],
          "is_piggy_defined": true,
          "is_soft_read_only": true,
          "is_hard_read_only": false
        }
      }
    ]
  }
}
```
```

--------------------------------

### GET /api/v3/oauth/clients/contact-attributes

Source: https://docs.leat.com/v3/oauth/contact-attributes

Retrieves a list of Contact Attributes for the account. This includes both default attributes and any custom attributes that have been created.

```APIDOC
## GET /api/v3/oauth/clients/contact-attributes

### Description
Display a list of Contact Attributes for your Account, including both the default ones and any Custom Attributes you've created.

### Method
GET

### Endpoint
`https://api.leat.com/api/v3/oauth/clients/contact-attributes`

### Parameters
#### Query Parameters
- **entity** (string) - REQUIRED - The type of Custom Attributes you want to retrieve.

#### Headers
- **Authorization** (string) - REQUIRED - `Bearer {{ access_token | api_key }}`
- **Accept** (string) - REQUIRED - `application/json`

### Response
#### Success Response (200)
- **data** (array) - A list of contact attribute objects.
  - **id** (integer) - The unique identifier for the attribute.
  - **name** (string) - The internal name of the attribute.
  - **label** (string) - The display name of the attribute.

### Response Example
```json
{
  "data": [
    {
      "id": 2204,
      "name": "avatar",
      "label": "Avatar"
    }
  ]
}
```
```

--------------------------------

### OAuth API Authorization - Personal Access Tokens

Source: https://docs.leat.com/v3/oauth/authorization

Explains how to use Personal Access Tokens for authorization on OAuth API routes. Tokens are generated in the Business Dashboard and added to requests via the Authorization header.

```APIDOC
## Authorization - Personal Access Tokens

### Description
Personal Access Tokens are the preferred method for authorization on our OAuth API routes. They can be generated within the Business Dashboard under 'Apps' > 'Integrations' > 'Personal Access Tokens'. Ensure you copy the token when it is first displayed, as it will not be shown again.

### Method
This documentation describes how to use an existing token, not the method to generate it.

### Endpoint
Not applicable for token usage description.

### Parameters
#### Request Headers
- **Authorization** (string) - Required - The token for authentication, formatted as `Bearer {{ Personal Access Token }}`.

### Request Example
`Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN`

### Response
No specific success response for header usage is detailed, but successful requests will return data as defined by the respective endpoints. An invalid token will result in a 401 error.

#### Error Response (401)
- **error** (string) - Description of the error, e.g., `invalid_token`.
```

--------------------------------

### GET /api/v3/oauth/clients/contacts/{contact_uuid}/prepaid-balance

Source: https://docs.leat.com/v3/oauth/contacts

Retrieves the prepaid balance of a Contact, identified by their UUID. This indicates the amount of prepaid funds available to the contact.

```APIDOC
## GET /api/v3/oauth/clients/contacts/{contact_uuid}/prepaid-balance

### Description
Retrieves the Prepaid Balance of a particular Contact, identified by their UUID. This shows the amount of prepaid funds available.

### Method
GET

### Endpoint
`https://api.leat.com/api/v3/oauth/clients/contacts/{{contact_uuid}}/prepaid-balance`

### Parameters
#### Headers
- **Authorization** (string) - Required - `Bearer {{ access_token | api_key }}`
- **Accept** (string) - Required - `application/json`

#### Query Parameters
- **contact_uuid** (string) - Required - The Contact's UUID.

### Response
#### Success Response (200)
- **data** (object) - Object containing the prepaid balance details.
  - **balance_in_cents** (integer) - The prepaid balance in cents.
  - **balance** (string) - The prepaid balance formatted as a currency string (e.g., '€50.00').
- **meta** (array) - Metadata associated with the response.

#### Response Example
```json
{
  "data": {
    "balance_in_cents": 5000,
    "balance": "€50.00"
  },
  "meta": []
}
```

#### Error Response
- **1003**: Invalid input.
- **55031**: Contact not found.
```

--------------------------------

### Find or Create Contact Async - API Request

Source: https://docs.leat.com/v3/oauth/contacts

This API endpoint is used to quickly find an existing contact by email or create a new one if it doesn't exist. It's optimized for speed, returning only the contact's UUID. The request requires an authorization token and the contact's email address.

```HTTP
GET https://api.leat.com/api/v3/oauth/clients/contacts/find-or-create/async
Headers:
Authorization: Bearer {{ access_token | api_key }}
Accept: application/json
Body:
{
  "email": "string (REQUIRED)"
}
```

--------------------------------

### GET /api/v3/oauth/clients/contacts/{contact_uuid}/contact-identifiers

Source: https://docs.leat.com/v3/oauth/contacts

Retrieves a list of Contact Identifiers associated with a specific Contact. This can include loyalty cards or other identification methods.

```APIDOC
## GET /api/v3/oauth/clients/contacts/{contact_uuid}/contact-identifiers

### Description
Retrieves a Contact's Contact Identifiers. These identifiers can be used for various purposes, such as identifying loyalty cards.

### Method
GET

### Endpoint
`https://api.leat.com/api/v3/oauth/clients/contacts/{{contact_uuid}}/contact-identifiers`

### Parameters
#### Headers
- **Authorization** (string) - Required - `Bearer {{ access_token | api_key }}`
- **Accept** (string) - Required - `application/json`

#### Query Parameters
- **contact_uuid** (string) - Required - The Contact's UUID from whom you want to retrieve the Contact Identifiers.

### Response
#### Success Response (200)
- **data** (array) - An array of contact identifier objects.
  - **name** (string) - The name of the identifier (e.g., 'Main Loyalty Card').
  - **value** (string) - The value of the identifier (e.g., 'ABCDE12356-90').
  - **active** (boolean) - Indicates if the identifier is active.
  - **default** (boolean) - Indicates if this is the default identifier.
  - **contact** (object) - Object containing contact details.
    - **uuid** (string) - The UUID of the associated contact.
- **meta** (array) - Metadata associated with the response.

#### Response Example
```json
{
  "data": [
    {
      "name": "Main Loyalty Card",
      "value": "ABCDE12356-90",
      "active": true,
      "default": true,
      "contact": {
        "uuid": "123abc-def789-qwerty-34567"
      }
    },
    {
      "name": "Fallback Card",
      "value": "QWERTY-7890",
      "active": true,
      "default": false,
      "contact": {
        "uuid": "123abc-def789-qwerty-34567"
      }
    }
  ],
  "meta": []
}
```

#### Error Response
- **1003**: Invalid input.
- **55031**: Contact not found.
```
Tokens:
Raw