# Eazyreach API Docs

## auth

### Create Authentication Token

`POST https://api.superflow.run/b2b/createAuthToken/`

Exchange your `clientId` and `clientSecret` for a token. Send it as `Authorization: Bearer <authToken>` on every other request. A token lasts 1 hour unless your key says otherwise: when it expires, create a new one.

#### Request Parameters
| Parameter | Type | Required |
|-----------|------|----------|
| clientId | string | yes |
| clientSecret | string | yes |

#### Response
| Field | Type | Notes |
|-------|------|-------|
| affectedRows | int | `1` on success |
| authToken | string | the bearer token |
| id | string | your account id |

#### Headers

- `Content-Type` · example: `application/json`

#### Request body

```json
{
	"clientId": "CLIENT_ID",
	"clientSecret": "CLIENT_SECRET"
}
```

#### Example request

```bash
curl -X POST 'https://api.superflow.run/b2b/createAuthToken/' \
  -H 'Content-Type: application/json' \
  -d '{
	"clientId": "CLIENT_ID",
	"clientSecret": "CLIENT_SECRET"
}'
```

#### Example response

```json
{
  "affectedRows": 0,
  "authToken": "string",
  "id": "string"
}
```

## wallet

### Get Wallet Balance

`GET https://api.superflow.run/b2b/getGreenBalance`

Return the current available balance of your Eazyreach prepaid wallet. Each enrichment lookup debits this balance.

#### Response
| Field   | Type   | Notes                                 |
|---------|--------|---------------------------------------|
| status  | string | `success` on 200                      |
| balance | number | available balance in account currency |

#### Errors
| Status | Message      | When                                |
|--------|--------------|-------------------------------------|
| 401    | unauthorized | bearer `auth_token` missing/invalid |

#### Headers

- `Authorization` · example: `Bearer AUTH_TOKEN`

#### Example request

```bash
curl -X GET 'https://api.superflow.run/b2b/getGreenBalance' \
  -H 'Authorization: Bearer AUTH_TOKEN'
```

#### Example response

```json
{
  "status": "success",
  "balance": 0
}
```

### Get Transaction History

`GET https://api.superflow.run/b2b/whatsubTransactionHistory`

Paginated wallet ledger — every debit (enrichment lookups) and credit (top-ups, refunds) for your account, newest first.

#### Query Parameters
| Parameter | Type | Required | Description                       |
|-----------|------|----------|-----------------------------------|
| limit     | int  | no       | max rows per page                 |
| offset    | int  | no       | rows to skip for pagination       |

#### Response
| Field        | Type   | Notes                                                              |
|--------------|--------|--------------------------------------------------------------------|
| status       | string | `success` on 200                                                   |
| transactions | array  | objects with `id`, `amount`, `type` (debit/credit), `created_at`, `description` |

#### Errors
| Status | Message      | When                                |
|--------|--------------|-------------------------------------|
| 401    | unauthorized | bearer `auth_token` missing/invalid |

#### Headers

- `Authorization` · example: `Bearer AUTH_TOKEN`

#### Query parameters

- `limit` · example: `LIMIT`
- `offset` · example: `OFFSET`

#### Example request

```bash
curl -X GET 'https://api.superflow.run/b2b/whatsubTransactionHistory?limit=LIMIT&offset=OFFSET' \
  -H 'Authorization: Bearer AUTH_TOKEN'
```

#### Example response

```json
{
  "status": "success",
  "transactions": []
}
```

## linkedin

### Linkedin phones b2b

`POST https://api.superflow.run/b2b/linkedin-phones`

Resolve **work phones** for a person from their LinkedIn profile URL.

#### Request Body Parameters
| Parameter    | Type   | Required | Description                                                       |
|--------------|--------|----------|-------------------------------------------------------------------|
| linkedinUrl  | string | yes      | full or short LinkedIn URL (e.g. `www.linkedin.com/in/<handle>`)  |

#### Response
| Field  | Type   | Notes                                                       |
|--------|--------|-------------------------------------------------------------|
| status | string | `success` on 200                                            |
| phones | array  | objects with `phone` (E.164), `type` (mobile/work), `source` |

#### Errors
| Status | Message                  | When                                |
|--------|--------------------------|-------------------------------------|
| 400    | invalid linkedinUrl      | URL missing or not parseable        |
| 401    | unauthorized             | bearer `auth_token` missing/invalid |
| 402    | insufficient balance     | wallet balance below lookup cost    |
| 404    | linkedin profile not found | URL does not resolve to a profile  |

#### Headers

- `Authorization` · example: `Bearer AUTH_TOKEN`
- `Content-Type` · example: `application/json`

#### Request body

```json
{
	"linkedinUrl": "www.linkedin.com/in/abhayhabbu"
}
```

#### Example request

```bash
curl -X POST 'https://api.superflow.run/b2b/linkedin-phones' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
	"linkedinUrl": "www.linkedin.com/in/abhayhabbu"
}'
```

#### Example response

```json
{
  "status": "success",
  "phones": []
}
```

### Linkedin work emails b2b

`POST https://api.superflow.run/b2b/linkedin-emails`

Resolve **work emails** for a person from their LinkedIn profile URL. Personal emails are a separate lookup, billed separately — see **Linkedin personal emails b2b**.

#### Request Body Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| linkedinUrl | string | yes | full or short LinkedIn URL (e.g. `www.linkedin.com/in/<handle>`) |

#### Response
| Field | Type | Notes |
|-------|------|-------|
| emails | string[] | work email addresses; an empty list when none are found |

#### Billing
Charged at your **work email** rate, only when an email is found. Repeating a lookup you have already made is free.

#### Errors
| Status | Message | When |
|--------|---------|------|
| 400 | linkedinUrl is required | `linkedinUrl` missing or not parseable |
| 401 | unauthorized / Zero Balance please recharge. | bearer `auth_token` missing or invalid, or the wallet is empty |
| 402 | Insufficient balance. Required: X, Available: Y | wallet balance below the lookup price |
| 403 | access denied | your role or plan does not include this lookup |

#### Headers

- `Content-Type` · example: `application/json`
- `Authorization` · example: `Bearer AUTH_TOKEN`

#### Request body

```json
{
	"linkedinUrl": "www.linkedin.com/in/abhayhabbu"
}
```

#### Example request

```bash
curl -X POST 'https://api.superflow.run/b2b/linkedin-emails' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -d '{
	"linkedinUrl": "www.linkedin.com/in/abhayhabbu"
}'
```

#### Example response

```json
{
  "emails": []
}
```

### Linkedin personal emails b2b

`POST https://api.superflow.run/b2b/linkedin-emails`

Resolve **personal emails** for a person from their LinkedIn profile URL. Same endpoint as work emails, with `emailType` set to `personal`: a separate lookup from different sources, billed separately. Work emails are not returned.

#### Request Body Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| linkedinUrl | string | yes | full or short LinkedIn URL (e.g. `www.linkedin.com/in/<handle>`) |
| emailType | string | yes | `personal` (omit it, or send `workEmail`, for work emails) |

#### Response
| Field | Type | Notes |
|-------|------|-------|
| emails | string[] | personal email addresses; an empty list when none are found |

#### Billing
Charged at your **personal email** rate, only when an email is found. Repeating a lookup you have already made is free.

#### Errors
| Status | Message | When |
|--------|---------|------|
| 400 | linkedinUrl is required | `linkedinUrl` missing or not parseable |
| 401 | unauthorized / Zero Balance please recharge. | bearer `auth_token` missing or invalid, or the wallet is empty |
| 402 | Insufficient balance. Required: X, Available: Y | wallet balance below the lookup price |
| 403 | access denied | your role or plan does not include this lookup |

#### Headers

- `Content-Type` · example: `application/json`
- `Authorization` · example: `Bearer AUTH_TOKEN`

#### Request body

```json
{
	"linkedinUrl": "www.linkedin.com/in/abhayhabbu",
	"emailType": "personal"
}
```

#### Example request

```bash
curl -X POST 'https://api.superflow.run/b2b/linkedin-emails' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -d '{
	"linkedinUrl": "www.linkedin.com/in/abhayhabbu",
	"emailType": "personal"
}'
```

#### Example response

```json
{
  "emails": []
}
```

## cin

### cin directors

`POST https://api.superflow.run/b2b/cin-directors`

Resolve a company's name, registered email and directors, with their DINs, from its CIN. For a whole sheet of CINs, use **CIN enrichment**.

To find a director's email and phone, send their DIN to **din emails** and **din phones**.

This call waits for the answer, which usually takes 10 to 15 seconds for a company we have not looked up before. If it times out, send it again: a company already charged for is free.

#### Request Body Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| cin | string | yes | the company's 21-character CIN |

#### Response
```json
{
  "cin": "U72900KA2015PTC000001",
  "company": "Example Technologies Private Limited",
  "company_email": "info@example.com",
  "directors": [
    { "din": "00000001", "name": "Asha Rao", "designation": "Director" },
    { "din": "00000002", "name": "Vikram Menon", "designation": "Additional Director" }
  ]
}
```

| Field | Type | Notes |
|-------|------|-------|
| cin | string | the CIN, in capitals |
| company | string | the company's name; empty when we find no directors |
| company_email | string | its registered email; empty when we don't have one |
| directors | array | each with `din`, `name` and `designation`; an empty list when we find none |

A DIN is a string of 8 digits, so it keeps its leading zeros. Remove them when you send it to **din emails** or **din phones**, which take a number.

#### Billing
Charged at your **CIN lookup** rate, only when we find directors. Repeating a lookup you have already made is free.

#### Errors
| Status | Message | When |
|--------|---------|------|
| 400 | cin is required | `cin` missing or blank |
| 400 | Not a valid CIN | `cin` is not in the 21-character form |
| 401 | Authorization token required | bearer `auth_token` missing or invalid |
| 402 | Insufficient balance. Recharge to look up this company. | wallet balance below the lookup price |
| 403 | API access is not enabled for this account. | code `api_access_disabled`. Contact us to turn it on |
| 403 | Bulk enrich is not enabled on your account. | code `section_disabled` |
| 403 | CIN lookup is not enabled on your account. Contact support to enable it. | CIN lookup is switched off for your account |
| 503 | Lookup unavailable right now. Not charged; try again later. | the lookup could not run |

#### Headers

- `Authorization` · example: `Bearer AUTH_TOKEN`
- `Content-Type` · example: `application/json`

#### Request body

```json
{
	"cin": "U72900KA2015PTC000001"
}
```

#### Example request

```bash
curl -X POST 'https://api.superflow.run/b2b/cin-directors' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
	"cin": "U72900KA2015PTC000001"
}'
```

#### Example response

```json
{
  "cin": "U72900KA2015PTC000001",
  "company": "Example Technologies Private Limited",
  "company_email": "info@example.com",
  "directors": [
    { "din": "00000001", "name": "Asha Rao", "designation": "Director" },
    { "din": "00000002", "name": "Vikram Menon", "designation": "Additional Director" }
  ]
}
```

## din

### din emails

`POST https://api.superflow.run/b2b/din-emails`

Resolve the **email addresses** linked to a director's DIN. For a whole sheet of DINs, use **DIN enrichment**.

#### Request Body Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| din_number | int | yes | Director Identification Number. Send it as a number, without leading zeros |

#### Response
| Field | Type | Notes |
|-------|------|-------|
| din_number | int | the DIN that was looked up |
| entity_name | string | the director's name, when known |
| emails | array | strings; an empty list when none are found |

#### Billing
Charged at your **DIN email** rate, only when an email is found. Repeating a lookup you have already made is free.

#### Errors
| Status | Message | When |
|--------|---------|------|
| 400 | din_number is required | `din_number` missing or 0 |
| 401 | Authorization token required, or Zero Balance please recharge. | bearer `auth_token` missing or invalid, or the wallet is empty |
| 402 | Insufficient balance. Required: X, Available: Y | wallet balance below the lookup price |
| 403 | DIN email lookup is not enabled on your account. | DIN email lookup is switched off for this account |
| 403 | API access is not enabled for this account. | code `api_access_disabled`. Contact us to turn it on |

#### Headers

- `Authorization` · example: `Bearer AUTH_TOKEN`
- `Content-Type` · example: `application/json`

#### Request body

```json
{
	"din_number": 6827866
}
```

#### Example request

```bash
curl -X POST 'https://api.superflow.run/b2b/din-emails' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
	"din_number": 6827866
}'
```

#### Example response

```json
{
  "din_number": 0,
  "entity_name": "string",
  "emails": []
}
```

### din phones

`POST https://api.superflow.run/b2b/din-phones`

Resolve the **phone numbers** linked to a director's DIN. For a whole sheet of DINs, use **DIN enrichment**.

#### Request Body Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| din_number | int | yes | Director Identification Number. Send it as a number, without leading zeros |

#### Response
| Field | Type | Notes |
|-------|------|-------|
| din_number | int | the DIN that was looked up |
| entity_name | string | the director's name, when known |
| phones | array | strings; an empty list when none are found |

#### Billing
Charged at your **DIN phone** rate, only when a phone is found. Repeating a lookup you have already made is free.

#### Errors
| Status | Message | When |
|--------|---------|------|
| 400 | din_number is required | `din_number` missing or 0 |
| 401 | Authorization token required, or Zero Balance please recharge. | bearer `auth_token` missing or invalid, or the wallet is empty |
| 402 | Insufficient balance. Required: X, Available: Y | wallet balance below the lookup price |
| 403 | DIN phone lookup is not enabled on your account. | DIN phone lookup is switched off for this account |
| 403 | API access is not enabled for this account. | code `api_access_disabled`. Contact us to turn it on |

#### Headers

- `Authorization` · example: `Bearer AUTH_TOKEN`
- `Content-Type` · example: `application/json`

#### Request body

```json
{
	"din_number": 6827866
}
```

#### Example request

```bash
curl -X POST 'https://api.superflow.run/b2b/din-phones' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
	"din_number": 6827866
}'
```

#### Example response

```json
{
  "din_number": 0,
  "entity_name": "string",
  "phones": []
}
```

## bulk

### CIN enrichment

`POST https://api.superflow.run/eazyreach/bulk-cin`

Turn a sheet of company CINs into each company's name, registered email and directors with their DINs. For one company, use **cin directors**.

The job runs in the background:
1. Send a CSV or XLSX with a header row, as an upload or a `file_url`.
2. Keep the `job_id` from the response.
3. Poll **Get bulk job** until the job ends, then read `results.rows` or download `results.download_url`.

To find each director's email and phone, send their DINs to **DIN enrichment**.

#### Request
Send `multipart/form-data` to upload a file, or JSON with a `file_url` as in the sample on this page.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| file | file | one of `file` or `file_url` | `.csv` or `.xlsx`, up to 10 MB and 2,000 rows. `.xls` is not accepted |
| file_url | string | one of `file` or `file_url` | a public `http` or `https` link to the file, which we download |
| identifier_column | string | no | the column holding the CIN. In a JSON request, send it as a query parameter |

If you leave out `identifier_column`, we use a column named `cin`, `cin number` or `cin no`, or one containing "corporate identity" or the word CIN. Failing that, we use the column whose first row holds a valid CIN.

#### Upload a file
```bash
curl -X POST https://api.superflow.run/eazyreach/bulk-cin \
  -H "Authorization: Bearer <auth_token>" \
  -F "file=@companies.csv" \
  -F "identifier_column=CIN"
```

#### Response
```json
{
  "success": true,
  "job_id": "3f9c2b7e-8a41-4d6f-9c21-5e7b1a0d4c88",
  "status": "pending",
  "detected": {
    "identifier_column": "CIN",
    "identifier_type": "cin",
    "row_count": 3,
    "valid_count": 2
  }
}
```

`valid_count` is how many rows hold a well-formed CIN. Rows that don't come back with status `invalid`.

#### Billing
Charged at your **CIN lookup** rate, once per company, only when we find its directors. A CIN repeated in the file, or one you have already looked up, is free. Use **Estimate CIN or DIN cost** to see the most a file can cost.

If your balance runs out part way, the job pauses with `status_reason` `out_of_credits`, and the rows left stay `pending` and are not charged. Recharge, then resume it with **Control a bulk job**. A company you were already charged for is free.

#### Errors
| Status | Message | When |
|--------|---------|------|
| 400 | no file supplied | neither `file` nor `file_url` was sent |
| 400 | file has no data rows | the file has a header and nothing else |
| 400 | A CIN file can have up to 2000 rows. This one has N. | too many rows |
| 400 | column "X" is not in the file | `identifier_column` does not match a header |
| 400 | could not find a CIN column in the file | send `identifier_column` |
| 400 | No valid CIN in the column "X". | no row holds a well-formed CIN |
| 401 | Authorization token required | bearer `auth_token` missing or invalid |
| 402 | Insufficient balance. Recharge to look up these companies. | wallet balance below one lookup |
| 403 | API access is not enabled for this account. | code `api_access_disabled`. Contact us to turn it on |
| 403 | Bulk enrich is not enabled on your account. | code `section_disabled` |
| 403 | CIN lookup is not enabled on your account. Contact support to enable it. | CIN lookup is switched off for your account |

#### Headers

- `Authorization` · example: `Bearer AUTH_TOKEN`
- `Content-Type` · example: `application/json`

#### Request body

```json
{
	"file_url": "https://example.com/companies.csv"
}
```

#### Example request

```bash
curl -X POST 'https://api.superflow.run/eazyreach/bulk-cin' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
	"file_url": "https://example.com/companies.csv"
}'
```

#### Example response

```json
{
  "success": true,
  "job_id": "3f9c2b7e-8a41-4d6f-9c21-5e7b1a0d4c88",
  "status": "pending",
  "detected": {
    "identifier_column": "CIN",
    "identifier_type": "cin",
    "row_count": 3,
    "valid_count": 2
  }
}
```

### DIN enrichment

`POST https://api.superflow.run/eazyreach/bulk-file`

Turn a sheet of DINs into each director's email and phone.

The job runs in the background:
1. Send a CSV or XLSX with a header row, as an upload or a `file_url`.
2. Keep the `job_id` from the response.
3. Poll **Get bulk job** until the job ends, then read `results.rows` or download `results.download_url`.

The results from **CIN enrichment** give you the DINs: its download has a `DIN` column, so you can send that file straight here.

#### Request
Send `multipart/form-data` to upload a file, or JSON with a `file_url` as in the sample on this page.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| file | file | one of `file` or `file_url` | `.csv` or `.xlsx`, up to 10 MB and 5,000 rows. `.xls` is not accepted |
| file_url | string | one of `file` or `file_url` | a public `http` or `https` link to the file, which we download |
| mode | string | recommended | `din`. Without it, a sheet that also has a LinkedIn column runs as a LinkedIn job. In a JSON request, send it as a query parameter |
| fields | array | no | `DIN_EMAIL`, `DIN_PHONE`. Leave it out for both |
| identifier_column | string | no | the column holding the DIN. In a JSON request, send it as a query parameter |

If you leave out `identifier_column`, we use a column named `din`, `din number`, `din_number` or `director_id`, or one containing "director identification".

#### Upload a file
```bash
curl -X POST https://api.superflow.run/eazyreach/bulk-file \
  -H "Authorization: Bearer <auth_token>" \
  -F "file=@directors.csv" \
  -F "mode=din" \
  -F 'fields=["DIN_EMAIL","DIN_PHONE"]'
```

#### Response
```json
{
  "success": true,
  "job_id": "8d27c1f0-5b3e-4a96-b7d2-1c9e6f30a8b4",
  "status": "pending",
  "detected": {
    "identifier_column": "DIN",
    "identifier_type": "din",
    "fields": ["DIN_EMAIL", "DIN_PHONE"],
    "dropped_fields": null,
    "row_count": 3,
    "urn_row_count": 0,
    "urn_resolvable": true,
    "source": "upload"
  }
}
```

`dropped_fields` lists any field you asked for that does not apply to a DIN file. `source` is `upload` or `url`. `urn_row_count` and `urn_resolvable` apply to LinkedIn files only.

#### Billing
Email and phone are charged separately, at your **DIN email** and **DIN phone** rates, only when found. A DIN repeated in the file, or one you have already looked up, is free. Use **Estimate CIN or DIN cost** to see the most a file can cost.

If your balance runs out part way, the job pauses with `status_reason` `out_of_credits`, and the rows left stay `pending` and are not charged. Recharge, then resume it with **Control a bulk job**. Anything you were already charged for is free.

#### Errors
| Status | Message | When |
|--------|---------|------|
| 400 | no file supplied | neither `file` nor `file_url` was sent |
| 400 | file has no data rows | the file has a header and nothing else |
| 400 | Invalid field "X" | `fields` holds an unknown value |
| 400 | none of the requested fields apply to a din file | `fields` holds only LinkedIn values |
| 400 | column "X" is not in the file | `identifier_column` does not match a header |
| 400 | could not find a LinkedIn URL, DIN, or name+mobile column | send `identifier_column` |
| 401 | Authorization token required | bearer `auth_token` missing or invalid |
| 403 | API access is not enabled for this account. | code `api_access_disabled`. Contact us to turn it on |
| 403 | Bulk enrich is not enabled on your account. | code `section_disabled` |

#### Headers

- `Authorization` · example: `Bearer AUTH_TOKEN`
- `Content-Type` · example: `application/json`

#### Query parameters

- `mode` · example: `din` — The file holds DINs. Send it here for a JSON request, or as a form field with an upload.

#### Request body

```json
{
	"file_url": "https://example.com/directors.csv",
	"fields": ["DIN_EMAIL", "DIN_PHONE"]
}
```

#### Example request

```bash
curl -X POST 'https://api.superflow.run/eazyreach/bulk-file?mode=din' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
	"file_url": "https://example.com/directors.csv",
	"fields": ["DIN_EMAIL", "DIN_PHONE"]
}'
```

#### Example response

```json
{
  "success": true,
  "job_id": "8d27c1f0-5b3e-4a96-b7d2-1c9e6f30a8b4",
  "status": "pending",
  "detected": {
    "identifier_column": "DIN",
    "identifier_type": "din",
    "fields": ["DIN_EMAIL", "DIN_PHONE"],
    "dropped_fields": null,
    "row_count": 3,
    "urn_row_count": 0,
    "urn_resolvable": true,
    "source": "upload"
  }
}
```

### LinkedIn enrichment

`POST https://api.superflow.run/eazyreach/bulk-file`

Turn a sheet of LinkedIn profiles into work emails, personal emails and phones. It uses the same route as **DIN enrichment**, with `mode=linkedin`.

The job runs in the background:
1. Send a CSV or XLSX with a header row, as an upload or a `file_url`.
2. Keep the `job_id` from the response.
3. Poll **Get bulk job** until the job ends, then read `results.rows` or download `results.download_url`.

#### Request
Send `multipart/form-data` to upload a file, or JSON with a `file_url` as in the sample on this page.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| file | file | one of `file` or `file_url` | `.csv` or `.xlsx`, up to 10 MB and 5,000 rows. `.xls` is not accepted |
| file_url | string | one of `file` or `file_url` | a public `http` or `https` link to the file, which we download |
| mode | string | no | `linkedin`. In a JSON request, send it as a query parameter |
| fields | array | no | `WORK_EMAIL`, `PERSONAL_EMAIL`, `PHONE`. Leave it out for all three |
| identifier_column | string | no | the column holding the profile link. In a JSON request, send it as a query parameter |

If you leave out `identifier_column`, we use a column named `linkedin url`, `linkedin_url`, `linkedin`, `profile url`, `profile_url` or `url`, or one containing the word linkedin.

#### Upload a file
```bash
curl -X POST https://api.superflow.run/eazyreach/bulk-file \
  -H "Authorization: Bearer <auth_token>" \
  -F "file=@leads.csv" \
  -F "mode=linkedin" \
  -F 'fields=["WORK_EMAIL","PHONE"]'
```

#### Response
```json
{
  "success": true,
  "job_id": "b15e7a62-0c94-4f1d-a8e3-6d2f9c47b031",
  "status": "pending",
  "detected": {
    "identifier_column": "LinkedIn URL",
    "identifier_type": "linkedin",
    "fields": ["WORK_EMAIL", "PHONE"],
    "dropped_fields": null,
    "row_count": 3,
    "urn_row_count": 0,
    "urn_resolvable": true,
    "source": "upload"
  }
}
```

`urn_row_count` is how many rows hold a Sales Navigator link. When `urn_resolvable` is `true` we convert those to public profiles; when it is `false` they come back `invalid`.

#### Billing
Each field is charged at its own rate, only when found. A profile you have already looked up is free.

If your balance runs out part way, the job pauses with `status_reason` `out_of_credits`. Recharge, then resume it with **Control a bulk job**.

#### Errors
| Status | Message | When |
|--------|---------|------|
| 400 | no file supplied | neither `file` nor `file_url` was sent |
| 400 | file has no data rows | the file has a header and nothing else |
| 400 | Invalid field "X" | `fields` holds an unknown value |
| 400 | none of the requested fields apply to a linkedin file | `fields` holds only DIN values |
| 400 | column "X" is not in the file | `identifier_column` does not match a header |
| 400 | could not find a LinkedIn URL, DIN, or name+mobile column | send `identifier_column` |
| 401 | Authorization token required | bearer `auth_token` missing or invalid |
| 403 | API access is not enabled for this account. | code `api_access_disabled`. Contact us to turn it on |
| 403 | Bulk enrich is not enabled on your account. | code `section_disabled` |
| 501 | address enrichment from a file is not available yet | no `mode`, and the sheet has only name and mobile columns |

#### Headers

- `Authorization` · example: `Bearer AUTH_TOKEN`
- `Content-Type` · example: `application/json`

#### Query parameters

- `mode` · example: `linkedin` — The file holds LinkedIn profiles. Send it here for a JSON request, or as a form field with an upload.

#### Request body

```json
{
	"file_url": "https://example.com/leads.csv",
	"fields": ["WORK_EMAIL", "PHONE"]
}
```

#### Example request

```bash
curl -X POST 'https://api.superflow.run/eazyreach/bulk-file?mode=linkedin' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
	"file_url": "https://example.com/leads.csv",
	"fields": ["WORK_EMAIL", "PHONE"]
}'
```

#### Example response

```json
{
  "success": true,
  "job_id": "b15e7a62-0c94-4f1d-a8e3-6d2f9c47b031",
  "status": "pending",
  "detected": {
    "identifier_column": "LinkedIn URL",
    "identifier_type": "linkedin",
    "fields": ["WORK_EMAIL", "PHONE"],
    "dropped_fields": null,
    "row_count": 3,
    "urn_row_count": 0,
    "urn_resolvable": true,
    "source": "upload"
  }
}
```

### Estimate CIN or DIN cost

`POST https://api.superflow.run/eazyreach/bulk-estimate-din`

See the most a CIN or DIN file can cost, and your balance, before you send it. Nothing is charged.

This is an upper bound. You pay only for data we find, and anything you have already looked up is free, so a job usually costs less.

#### Request Body Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| kind | string | yes | `cin` or `din` |
| count | int | yes | how many rows the file has |
| fields | array | for `din` | `DIN_EMAIL`, `DIN_PHONE`. Send the fields you will request: with none, the estimate is 0 |

#### Response
```json
{
  "success": true,
  "max_cost_paise": 50000,
  "unit_paise": 500,
  "balance_paise": 120000
}
```

| Field | Type | Notes |
|-------|------|-------|
| max_cost_paise | number | `count` × `unit_paise` |
| unit_paise | number | the most one row can cost, at your rates |
| balance_paise | number | your available balance |

All amounts are in paise: 100 paise is ₹1.

#### Errors
| Status | Message | When |
|--------|---------|------|
| 400 | count is required | `count` missing or not above 0 |
| 401 | Authorization token required | bearer `auth_token` missing or invalid |
| 403 | Bulk enrich is not enabled on your account. | code `section_disabled` |

#### Headers

- `Authorization` · example: `Bearer AUTH_TOKEN`
- `Content-Type` · example: `application/json`

#### Request body

```json
{
	"kind": "din",
	"count": 100,
	"fields": ["DIN_EMAIL", "DIN_PHONE"]
}
```

#### Example request

```bash
curl -X POST 'https://api.superflow.run/eazyreach/bulk-estimate-din' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
	"kind": "din",
	"count": 100,
	"fields": ["DIN_EMAIL", "DIN_PHONE"]
}'
```

#### Example response

```json
{
  "success": true,
  "max_cost_paise": 50000,
  "unit_paise": 500,
  "balance_paise": 120000
}
```

### Get bulk job

`GET https://api.superflow.run/eazyreach/bulk-jobs/{job_id}`

Read a bulk job's progress and rows. Call this with the `job_id` from **CIN enrichment**, **DIN enrichment** or **LinkedIn enrichment**.

Poll every 5 to 15 seconds until `status` is `completed`, `failed` or `cancelled`. A job keeps running if your token expires: create a new token and carry on polling. CIN and DIN jobs save their rows as they finish, every 5 seconds, or every 15 above 1,000 rows, so you can read them while the job runs.

#### Response
```json
{
  "job_id": "3f9c2b7e-8a41-4d6f-9c21-5e7b1a0d4c88",
  "job_type": "bulk_cin_to_din",
  "status": "completed",
  "total_count": 3,
  "completed_count": 3,
  "success_count": 1,
  "results": {
    "download_url": "https://files.example.com/eazyreach/bulk/3f9c2b7e.xlsx",
    "rows": [
      {
        "row": { "Company": "Example Technologies", "CIN": "U72900KA2015PTC000001" },
        "cin": "U72900KA2015PTC000001",
        "status": "found",
        "company": "Example Technologies Private Limited",
        "company_email": "info@example.com",
        "directors": [
          { "din": "00000001", "name": "Asha Rao", "designation": "Director" },
          { "din": "00000002", "name": "Vikram Menon", "designation": "Additional Director" }
        ]
      },
      {
        "row": { "Company": "Example Traders", "CIN": "U51909TN2008PTC000002" },
        "cin": "U51909TN2008PTC000002",
        "status": "not_found"
      },
      {
        "row": { "Company": "Typo in the sheet", "CIN": "NOT-A-CIN" },
        "cin": "NOT-A-CIN",
        "status": "invalid",
        "message": "Not a valid CIN"
      }
    ]
  },
  "input": {
    "source": { "filename": "companies.csv", "via": "upload" },
    "identifier_column": "CIN",
    "identifier_type": "cin",
    "headers": ["Company", "CIN"],
    "row_count": 3
  },
  "created_at": "2026-11-03T13:20:05.112+00:00",
  "updated_at": "2026-11-03T13:20:41.530+00:00",
  "completed_at": "2026-11-03T13:20:41.530+00:00"
}
```

| Field | Type | Notes |
|-------|------|-------|
| job_type | string | `bulk_cin_to_din` for a CIN file, `bulk_reveal_file` for a DIN or LinkedIn file. `input.identifier_type` tells those two apart |
| status | string | see the statuses below |
| status_reason | string | why a job is paused or cancelled |
| total_count | int | rows in the file |
| completed_count | int | rows that have run. It counts an invalid row as run |
| success_count | int | rows with `status` `found` |
| results | object | `null` until the first rows are saved |
| results.rows | array | one object per row of your file, in order |
| results.download_url | string | the finished file, as **.xlsx**. Anyone with the link can open it |
| input | object | what you uploaded and the column we used |
| error_message | string | why a job failed |
| completed_at | string | when the job's last rows were saved |

#### Job statuses
| Status | What it means | What to do |
|--------|---------------|------------|
| pending | waiting to start | keep polling |
| processing | running | keep polling |
| paused | `status_reason` is `paused_by_user`, `out_of_credits`, `not_allowed`, `billing_error` or `needs_resume` | resume it with **Control a bulk job** |
| completed | every row has run | read the rows, or download the file |
| failed | it stopped early, and `error_message` says what to do | check `completed_count`: above 0, the rows that ran are kept |
| cancelled | you cancelled it | keep polling until `completed_at` is set: the last rows are saved once the rows already running finish |

#### Row statuses
| Status | What it means | Charged |
|--------|---------------|---------|
| found | we found data | yes, unless you already had it |
| not_found | we found nothing, or could not look it up, with the reason in `message` | no |
| invalid | not a valid CIN, DIN or LinkedIn link | no |
| error | the lookup could not run. Try again later | no |
| not_processed | the job was cancelled before this row ran | no |
| pending | has not run yet. You see this while a CIN or DIN job runs or is paused | no |

#### Row fields
Every row has `row` (your own columns), `status`, and `message` when there is a reason to give. The rest depends on the job.

| Job | Fields |
|-----|--------|
| CIN | `cin`, `company`, `company_email`, `directors` (each with `din`, `name`, `designation`) |
| DIN | `din_email`, `din_phone`. Several values are separated by a comma |
| LinkedIn | `work_email`, `personal_email`, `phone`. Several values are separated by a comma |

A DIN row looks like this:
```json
{
  "row": { "Name": "Asha Rao", "DIN": "00000001" },
  "status": "found",
  "din_email": "asha@example.com",
  "din_phone": "9000000001"
}
```

**While a LinkedIn job runs**, `results` is a plain array in row order: `null` for a row that has not run, otherwise an object with `linkedinUrl`, `success`, `work_emails`, `personal_emails`, `phones`, `name` and `error`. It becomes `results.rows` when the job ends.

#### The download
The file keeps your columns and adds the results. A CIN file has one row per director on a sheet called `Directors`, with `Company name`, `Company email`, `DIN`, `Director name` and `Designation` added. Companies with no directors go on a second sheet called `No result`, with a `Reason`.

#### Errors
| Status | Message | When |
|--------|---------|------|
| 401 | Authorization token required | bearer `auth_token` missing or invalid |
| 403 | You don't have permission to run bulk enrichment. | your role does not include bulk enrichment |
| 404 | Job not found | the id is wrong, or the job belongs to another account |

#### Headers

- `Authorization` · example: `Bearer AUTH_TOKEN`

#### Path parameters

- `job_id` · example: `JOB_ID` — The job_id you got when you sent the file.

#### Example request

```bash
curl -X GET 'https://api.superflow.run/eazyreach/bulk-jobs/{job_id}' \
  -H 'Authorization: Bearer AUTH_TOKEN'
```

#### Example response

```json
{
  "job_id": "3f9c2b7e-8a41-4d6f-9c21-5e7b1a0d4c88",
  "job_type": "bulk_cin_to_din",
  "status": "completed",
  "total_count": 3,
  "completed_count": 3,
  "success_count": 1,
  "results": {
    "download_url": "https://files.example.com/eazyreach/bulk/3f9c2b7e.xlsx",
    "rows": [
      {
        "row": { "Company": "Example Technologies", "CIN": "U72900KA2015PTC000001" },
        "cin": "U72900KA2015PTC000001",
        "status": "found",
        "company": "Example Technologies Private Limited",
        "company_email": "info@example.com",
        "directors": [
          { "din": "00000001", "name": "Asha Rao", "designation": "Director" },
          { "din": "00000002", "name": "Vikram Menon", "designation": "Additional Director" }
        ]
      },
      {
        "row": { "Company": "Example Traders", "CIN": "U51909TN2008PTC000002" },
        "cin": "U51909TN2008PTC000002",
        "status": "not_found"
      },
      {
        "row": { "Company": "Typo in the sheet", "CIN": "NOT-A-CIN" },
        "cin": "NOT-A-CIN",
        "status": "invalid",
        "message": "Not a valid CIN"
      }
    ]
  },
  "input": {
    "source": { "filename": "companies.csv", "via": "upload" },
    "identifier_column": "CIN",
    "identifier_type": "cin",
    "headers": ["Company", "CIN"],
    "row_count": 3
  },
  "created_at": "2026-11-03T13:20:05.112+00:00",
  "updated_at": "2026-11-03T13:20:41.530+00:00",
  "completed_at": "2026-11-03T13:20:41.530+00:00"
}
```

### Control a bulk job

`POST https://api.superflow.run/eazyreach/bulk-jobs/{job_id}/{action}`

Pause, resume or cancel a job, or rerun a finished LinkedIn job. Send no body.

| Action | CIN and DIN files | LinkedIn files | What it does |
|--------|-------------------|----------------|--------------|
| cancel | yes | yes | Stops the job for good. Rows that ran stay, and stay charged. Rows that did not run come back `not_processed` and are not charged |
| pause | yes | yes | Stops starting new rows. Rows already running finish |
| resume | yes | yes | Runs the rest of a paused job. A row you were already charged for is free |
| retry | no | yes | Runs a finished job's failed rows again |
| rerun | no | yes | Runs every row of a finished job again. Rows you already have are free |

A row already running when you cancel can finish first. On a DIN file it is charged if it finds data. On a CIN file, a company that comes back after the cancel is not charged.

To finish a cancelled or failed CIN or DIN file, send the file again. Anything you already paid for is free.

#### Response
```json
{
  "success": true,
  "job_id": "3f9c2b7e-8a41-4d6f-9c21-5e7b1a0d4c88",
  "status": "cancelled",
  "status_reason": "cancelled_by_user"
}
```

#### Errors
| Status | Message | When |
|--------|---------|------|
| 401 | Authorization token required | bearer `auth_token` missing or invalid |
| 403 | You don't have permission to run bulk enrichment. | your role does not include bulk enrichment |
| 404 | Job not found, or Unknown action | the id is wrong, the job belongs to another account, or the action is not one of the five above |
| 409 | This job has already finished. | the job already ended |
| 409 | You're out of credits. Recharge, then resume. | `resume` on a CIN file with too little balance for one company |
| 409 | This job can't be run again. Upload the file again. | `retry` or `rerun` on a CIN or DIN file |
| 409 | This job can't be resumed. Upload the file again to finish it. | `resume` on a CIN or DIN file that saved no rows before it stopped |
| 409 | Only a finished job can be run again. | `retry` or `rerun` while the job runs |
| 409 | No failed rows to run again. | `retry` when every row has an answer |

A 409 response also has the job's current `status`.

#### Headers

- `Authorization` · example: `Bearer AUTH_TOKEN`

#### Path parameters

- `job_id` · example: `JOB_ID` — The job_id you got when you sent the file.
- `action` · example: `cancel` — cancel, pause, resume, retry or rerun.

#### Example request

```bash
curl -X POST 'https://api.superflow.run/eazyreach/bulk-jobs/{job_id}/{action}' \
  -H 'Authorization: Bearer AUTH_TOKEN'
```

#### Example response

```json
{
  "success": true,
  "job_id": "3f9c2b7e-8a41-4d6f-9c21-5e7b1a0d4c88",
  "status": "cancelled",
  "status_reason": "cancelled_by_user"
}
```