# 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>