> ## Documentation Index
> Fetch the complete documentation index at: https://docs.emailbison.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Adding Leads

You can add leads one at a time using the API, or bulk add leads in a CSV file using the UI or the API.

## Adding Single Leads

<Tabs>
  <Tab title="API" icon="binary">
    You can create a single lead by sending a `POST` request at the [following endpoint](https://dedi.emailbison.com/api/reference#tag/leads/post/api/leads).

    ```bash theme={null}
    /api/leads
    ```

    The required fields are `first_name`, `last_name`, and `email`.

    The optional fields are `title`, `company`, `notes`, and [`custom variables`](/leads/custom-variables).

    <Note>
      Custom variables need to be created in advance in each workspace.
    </Note>

    The following is an example of creating a single lead:

    <CodeGroup>
      ```bash curl theme={null}
      curl https://dedi.emailbison.com/api/leads \
        --request POST \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
        --data '{
        "first_name": "John",
        "last_name": "Doe",
        "email": "john@doe.com",
        "title": "Engineer",
        "company": "John Doe Company",
        "notes": "Important client",
        "custom_variables": [
          {
            "name": "phone number",
            "value": "9059999999"
          }
        ]
      }'
      ```

      ```JavaScript JavaScript theme={null}
      fetch('https://dedi.emailbison.com/api/leads', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          Authorization: 'Bearer YOUR_SECRET_TOKEN'
        },
        body: JSON.stringify({
          first_name: 'John',
          last_name: 'Doe',
          email: 'john@doe.com',
          title: 'Engineer',
          company: 'John Doe Company',
          notes: 'Important client',
          custom_variables: [{
            name: 'phone number',
            value: '9059999999'
          }]
        })
      })
      ```

      ```Python Python theme={null}
      headers = {
          'Content-Type': 'application/json',
          'Authorization': 'Bearer YOUR_SECRET_TOKEN',
      }

      json_data = {
          'first_name': 'John',
          'last_name': 'Doe',
          'email': 'john@doe.com',
          'title': 'Engineer',
          'company': 'John Doe Company',
          'notes': 'Important client',
          'custom_variables': [
              {
                  'name': 'phone number',
                  'value': '9059999999',
              },
          ],
      }

      response = requests.post('https://dedi.emailbison.com/api/leads', headers=headers, json=json_data)
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Bulk Uploading Leads

<Tabs>
  <Tab title="API" icon="binary">
    <Warning>
      Do **not** set the `content-type` header for this request.

      It will be automatically set to `multipart/form-data` because of the file included.
    </Warning>

    Bulk upload leads with a `POST` request to the following endpoint.

    ```bash theme={null}
    /api/leads/bulk/csv
    ```

    The request takes the following fields:

    <ParamField body="name" type="string" required>
      The name of the lead list that will be created
    </ParamField>

    <ParamField body="csv" type="FILE" required>
      The CSV file.
    </ParamField>

    <ParamField body="columnsToMap[first_name][]" type="string" required>
      The name of the CSV header column that corresponds to `first_name` on EmailBison
    </ParamField>

    <ParamField body="columnsToMap[last_name][]" type="string" required>
      The name of the CSV header column that corresponds to `last_name` on EmailBison
    </ParamField>

    <ParamField body="columnsToMap[email][]" type="string" required>
      The name of the CSV header column that corresponds to `email` on EmailBison
    </ParamField>

    <ParamField body="columnsToMap[{OTHER}][]" type="string">
      The remaining fields you would like to map - including custom variables - each getting their own field.
    </ParamField>

    The following is an example of a request to bulk upload a CSV file:

    <CodeGroup>
      ```Bash curl theme={null}
      curl https://dedi.emailbison.com/api/leads/bulk/csv \
        --request POST \
        --header 'Content-Type: multipart/form-data' \
        --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
        --data "{
            "name":"John Does list",
            "csv":"/Users/Jack/Desktop/list.csv",
            "columnsToMap[0][first_name]":"name",
            "columnsToMap[0][last_name]":"last name",
            "columnsToMap[0][email]":"email",
            "columnsToMap[0][company]":"company name",
            "columnsToMap[0][my_custom_variable]":"my_custom_variable"
          }"
      ```

      ```JavaScript JavaScript theme={null}
      let formData = new FormData();

      formData.append('file', fs.createReadStream('/Users/Jack/Desktop/list.csv'));
      formData.append('name', 'John Does List');
      formData.append('columnsToMap[0][first_name]', 'name');
      formData.append('columnsToMap[0][last_name]', 'last name');
      formData.append('columnsToMap[0][email]', 'email address');
      formData.append('columnsToMap[0][company]', 'company name');
      formData.append('columnsToMap[0][my_custom_variable]', 'my custom variable');

      fetch("https://dedi.emailbison.com/api/leads/bulk/csv",
          {
              body: formData,
              method: "POST"
          });
      })
      ```

      ```Python Python theme={null}
      url = 'https://dedi.emailbison.com/api/leads/bulk/csv'
      fp = '/Users/Jack/Desktop/list.csv'

      files = {'file': open(fp, 'rb')}
      payload = {
                  'name': 'my list'
                  'columnsToMap[0][first_name]':'name',
                  'columnsToMap[0][last_name]':'last name',
                  'columnsToMap[0][email]':'email',
                  'columnsToMap[0][company]':'company name',
                  'columnsToMap[0][my_custom_variable]':'my_custom_variable'
              }

      response = requests.post(url, files=files, data=payload)
      ```
    </CodeGroup>
  </Tab>

  <Tab title="UI" icon="browser">
    ## Bulk Uploading Leads

    <Note>There is a 50,000 lead limit per CSV file</Note>

    Navigate to `Contacts` -> `Import New Contacts`.

    You can download and refer to the Sample CSV file on proper formatting.
  </Tab>
</Tabs>