# Customers

Received's Customers' APIs allow our users to manage their customers and subscribers. The APIs support operations such as creating a new customer, updating existing customers and fetching customers' related data.  

{% code title="Endpoint on this page" lineNumbers="true" %}

```javascript
POST https://api.received.ai/api/customers
GET https://api.received.ai/api/entities/<entity_ref>
GET https://api.received.ai/api/customers/names
GET https://api.received.ai/api/entities/names
```

{% endcode %}

{% hint style="info" %}
Don't forget! APIs must include:

1. **Bearer Token** - return from the login call
2. **API version** - {"Version": "V0"}
   {% endhint %}

## Adding Customer For Debit Entity

Adding a new customer for the receiving entity involves registering their details and payment information, enhancing the entity's client base and opening avenues for increased revenue streams.

### Add Customer

{% code lineNumbers="true" %}

```javascript
POST https://api.received.ai/api/customers
```

{% endcode %}

{% code title="Mandatory request " lineNumbers="true" %}

```javascript
{
  "name": "Acme",
  "email": "admin1@acme.com, admin2@acme.com",
}
```

{% endcode %}

<pre class="language-javascript" data-title="Extensive request" data-line-numbers><code class="lang-javascript"><strong>{
</strong>  "name": "Acme",
  "legal_name": "Acme Inc.",
  "email": "admin1@acme.com, admin2@acme.com",
  "ein": "12-3456789",
  "phone": {
    "countryCode": "1",
    "phone": "2121234567"
  },
  "country": "United States",
  "country_state": "NY",
  "city": "New York",
  "zip_code": "13601",
  "billing_address": "643 Mundy St, Watertown",
  "shipping_address": "643 Mundy St, Watertown",
  "currency": "USD",
  "tax": 17,
  "entity_ref": "9f9f6a42-fba0-4fb5-ac7a-e83ac2c045a9",
  "net_terms": 30,
  "billing_bank_transfer_details": {
    "billing_account_id": "12345678-1234-1234-1234-1234567890ab"
  },
  "billing_online_payment_details": {
    "auto_charge": true,
    "payment_gateway_id": "87654321-4321-4321-4321-0987654321ba",
    "payment_gateway_card_id": "card_abcdef1234567890"
  },
  "billing_crypto_details": {
    "address": "0x1234567890abcdef1234567890abcdef12345678",
    "tokens": ["BTC", "ETH"]
  },
  "settings": {
    "attach_usage_logs_csv": false,
    "attach_usage_logs_pdf": true
  }
}
</code></pre>

#### Responses

{% code lineNumbers="true" %}

```javascript
{
  "customer_ref": {{customer_ref}}
}
```

{% endcode %}

#### Request Schema

<table><thead><tr><th width="350">Term</th><th width="99">Type</th><th width="330">Description </th><th width="378">Example</th></tr></thead><tbody><tr><td><code>name</code><mark style="color:red;">*</mark></td><td><mark style="color:purple;">String</mark></td><td>Company name</td><td>Acme</td></tr><tr><td><code>email</code><mark style="color:red;">*</mark></td><td><mark style="color:purple;">String</mark></td><td>Company's email addresses comma separated</td><td>admin1@acme.com, admin2@acme.com</td></tr><tr><td><code>legal_name</code></td><td><mark style="color:purple;">String</mark></td><td>Company's legal name - documents use</td><td>Acme Inc.</td></tr><tr><td><code>ein</code></td><td><mark style="color:purple;">Number</mark></td><td>Employer identification number</td><td>12-3456789</td></tr><tr><td><code>phone</code></td><td><mark style="color:purple;">Number</mark></td><td>Company's phone number in international format (7-20 digits)</td><td>2121234567</td></tr><tr><td><code>country_code</code></td><td><mark style="color:purple;">Number</mark></td><td>Country code (1-4 digits)</td><td>123</td></tr><tr><td><code>country</code>*</td><td><mark style="color:purple;">String</mark></td><td>Company's country of operation</td><td>United States</td></tr><tr><td><code>country_state</code></td><td><mark style="color:purple;">String</mark></td><td>Company's state of operation</td><td>NY</td></tr><tr><td><code>city</code></td><td><mark style="color:purple;">String</mark></td><td>Company's city of operation</td><td>New York</td></tr><tr><td><code>zip-code</code></td><td><mark style="color:purple;">Number</mark></td><td>Company's zip code</td><td>10001</td></tr><tr><td><code>billing_address</code></td><td><mark style="color:purple;">String</mark></td><td>Company's billing address</td><td>643 Mundy St, Watertown, New York(NY), 13601</td></tr><tr><td><code>shipping_address</code></td><td><mark style="color:purple;">String</mark></td><td>Company's shipping address</td><td>643 Mundy St, Watertown, New York(NY), 13601</td></tr><tr><td><code>currency</code></td><td><mark style="color:purple;">String</mark></td><td>The default currency that is used for this company</td><td>USD</td></tr><tr><td><code>tax</code></td><td><mark style="color:purple;">Number</mark></td><td>Value Added Tax - in percentage</td><td>17</td></tr><tr><td><code>entity_ref</code></td><td><mark style="color:purple;">String</mark></td><td>The ID of the related supplier entity</td><td>fae8fc36-d321-473f-9890-a9cb16deb4dd</td></tr><tr><td><code>net_terms</code>*</td><td><mark style="color:purple;">Number</mark></td><td>The default net terms used for this company, It must be a positive number or a payment term: "DUE_UPON_RECEIPT", "DUE_UPON_USAGE"</td><td>30</td></tr><tr><td><code>billing_bank_transfer_details</code><br><br>  <code>billing_account_id</code></td><td><mark style="color:purple;">Object</mark><br><br><mark style="color:purple;">String</mark></td><td>Bank account details<br><br>The ID of the bank account</td><td><pre class="language-javascript"><code class="lang-javascript"><strong>{
</strong>  "billing_account_id": "3a7b0f7d-fdf6-4f54-90f4-2307b73ae85f"
}
</code></pre></td></tr><tr><td><code>billing_online_payment_details</code><br><br>  <code>auto_charge</code><br><br>  <code>payment_gateway_id</code><br>  <code>payment_gateway_card_id</code><br><br></td><td><mark style="color:purple;">Object</mark><br><br><mark style="color:purple;">Boolean</mark><br><br><mark style="color:purple;">String</mark><br><mark style="color:purple;">String</mark><br><br></td><td>Online payment details<br><br>Indicates whether the charging should be automatic or not<br>The ID of the payment gateway<br>The ID of a specific card defined in the payment gateway account, such as Stripe card id</td><td><pre class="language-javascript"><code class="lang-javascript"><strong>{
</strong>  "auto_charge": true,
  "payment_gateway_id": "3a7b0f7d-fdf6-4f54-90f4-2307b73ae85f",
  "payment_gateway_card_id": "card_abcdef1234567890"
}
</code></pre></td></tr><tr><td><p><code>billing_crypto_details</code><br>  <code>address</code><br>  <code>tokens</code></p><p></p></td><td><mark style="color:purple;">Object</mark><br><mark style="color:purple;">String</mark><br><mark style="color:purple;">Array</mark><br></td><td>The details of the crypto wallet<br>The address of the crypto wallet<br>The crypto tokens that supported by the wallet </td><td><pre class="language-javascript"><code class="lang-javascript"><strong>{
</strong>  "address": "1Lbcfr7sAHTD9CgdQo3HTMTkV8LK4ZnX71",
  "tokens": ["BTC", "ETH"]
}
</code></pre></td></tr><tr><td><code>settings</code><br>  <code>attach_useage_logs_csv</code><br>  <code>attach_useage_logs_pdf</code></td><td><mark style="color:purple;">String</mark><br><mark style="color:purple;">Boolean</mark><br><mark style="color:purple;">Boolean</mark></td><td><p>Set usage reports for Invoice email: </p><p>Attach logs csv to invoice email<br>Attach logs appendix to invoice PDF</p></td><td><pre class="language-javascript"><code class="lang-javascript">{
  "attach_usage_logs_csv": false,
  "attach_usage_logs_pdf": true
}
</code></pre></td></tr></tbody></table>

#### Response Schema

<table><thead><tr><th width="187">Term</th><th width="88">Type</th><th>Description</th><th>Exmaple</th></tr></thead><tbody><tr><td><code>customer_ref</code></td><td><mark style="color:purple;">String</mark></td><td>Customer reference</td><td>dcaff9c0-4a9c-4d01-b2dc-0da7efcc616c </td></tr></tbody></table>

### Get Debit Entity

{% code lineNumbers="true" %}

```javascript
GET https://api.received.ai/api/entities/<entity_ref>
```

{% endcode %}

#### Responses

{% code lineNumbers="true" %}

```javascript
{
  "entity_ref": "db93868d-01f6-40dc-8609-0a314969d03b",
  "name": "ACME",
  "legal_name": "ACME Ltd.",
  "email": "admin1@acme.com, admin2@acme.com",
  "registration_number": "12-3456789",

  "billing_details": {
    "billing_accounts": [
      {
        "billing_account_id": "0c013466-84f4-48a4-a91b-5cc9808fc3f5",
        "bank_name": "Bank Of America",
        "bank_code": "123",
        "branch": "123",
        "account": "123123",
        "account_name": "US BOA Account",
        "iban": "IL62 0108 0000 0009 9999 999",
        "swift": "BOFAUS3N",
        "routing": "071904779",
        "address": "643 Mundy St, Watertown, New York(NY), 13601",
      }
    ],
    "payment_gateways": [
      {
        "payment_gateway_id": "b59ec2d9-379a-46cf-b69c-fdb5fa47787d",
        "provider": "STRIPE",
        "payment_gateway_card_id": "acct_1OPTJWKoIU7lFy9r",
        "account_name": "US Account"
      }
    ]
  },
  
  "country": "United States",  
  "country_state": "NY",
  "city": "New York",
  "address": "643 Mundy St, Watertown",
  "phone": {
    "countryCode": "1",
    "phone": "2121234567"
  },
  "zip_code": "13601",
}
```

{% endcode %}

## Explore More APIs

Delves into additional customers methods, broadening your integration capabilities and enhancing secure access

### List All Customers

{% code title="All Customers" lineNumbers="true" %}

```javascript
GET https://api.received.ai/api/customers/names
```

{% endcode %}

{% code title="Response" lineNumbers="true" %}

```javascript
{
    "customers": [
        {
            "customer_ref": {{customer_ref}},
            "customer_name": {{customer_name}},
            "customer_legal_name": {{customer_legal_name}}
        }
    ]
}
```

{% endcode %}

### Filter List Of Customers

{% code title="Filter list of customers" overflow="wrap" lineNumbers="true" %}

```javascript
GET https://api.received.ai/api/customers/names/filter?customer_name={{customer_name}}&orderBy=name&order=ASC
```

{% endcode %}

{% code title="Response" lineNumbers="true" %}

```javascript
{
    "customers": [
        {
            "customer_ref": {{customer_ref}},
            "customer_name": {{customer_name}},
            "customer_legal_name": {{customer_legal_name}}
        }
    ],
    "count": 1,
    "total": 1
}
```

{% endcode %}

### Customer Invoices

See [invoices API](https://docs.received.ai/api-docs/invoices#get-customer-contract-invoices)

### List All Debit Entities

{% code lineNumbers="true" %}

```javascript
GET https://api.received.ai/api/entities/names
```

{% endcode %}

#### Response

<pre class="language-javascript" data-line-numbers><code class="lang-javascript">{
    "entities": [
        {
            "entity_ref": {{entity_ref}},
            "entity_name": {{entity_name}},
            "entity_legal_name": {{entity_legal_name}}
        }
    ]
<strong>}
</strong></code></pre>

#### Response Schema

<table><thead><tr><th width="187">Term</th><th width="88">Type</th><th width="297">Description</th><th width="359">Exmaple</th></tr></thead><tbody><tr><td>entity_ref</td><td><mark style="color:purple;">String</mark></td><td>The ID of the supplier entity</td><td>dcaff9c0-4a9c-4d01-b2dc-0da7efcc616c </td></tr><tr><td>entity_name</td><td><mark style="color:purple;">String</mark></td><td>The name of the supplier entity</td><td>Acme</td></tr><tr><td>entity_legal_name</td><td><mark style="color:purple;">String</mark></td><td>The legal name of the supplier entity - used of documents</td><td>Acme Ltd.</td></tr></tbody></table>


---

# 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://docs.received.ai/api-docs/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.