---
updatedAt: 2025-06-16T22:59:02.000Z
---

Fetch the complete documentation index at: https://developers.neverbounce.com/llms.txt. Use this file to discover all available pages before exploring further.

# /create

> 📘 Usage Guidelines
>
> Please be sure to review our usage guidelines for the bulk API [here](/v4.0/reference#section-bulk-verification).

The jobs create endpoint allows you create verify multiple emails together, the same way you would verify lists in the dashboard. This endpoint will create a job and process the emails in the list (if `auto_start` is enabled) asynchronously. **Verification results are not returned in the response.** Read more about how to verify lists of emails [here](/v4.0/docs/verifying-a-list).

## Auto Parse

This will enable or disable the indexing process from automatically starting as soon as you create a job. If set to `0` or `false` you will need to call the `/parse` endpoint after the job has been created to begin indexing. *Defaults to 0*

## Auto Start

This will enable or disable the job from automatically beginning the verification process once it has been parsed. If this is set to `0` or `false` you will need to call the `/start` endpoint to begin verification. Setting this to `1` or `true` will start the job and deduct the credits. *Defaults to 0*

## Run Sample

This endpoint has the ability to run a sample on the list and provide you with an estimated bounce rate without costing you. Based on the estimated bounce rate you can decide whether or not to perform the full validation or not. You can start validation by calling the `/start` endpoint. Read more about running a sample [here](/v4.0/docs/running-a-free-analysis). *Defaults to 0*

## Input & Input Location

This endpoint can receive input in multiple ways. The `input_location` parameter describes the contents of the `input` parameter. The `input` parameter may be an array of objects containing emails or a file hosted at a remote URI.

### Remote URL

Using a remote URL allows you to host the file and provide us with a direct link to it. The file should be a list of emails separated by line breaks or a standard CSV file. We support most common file transfer protocols and their authentication mechanisms. When using a URL that requires authentication be sure to pass the username and password in the URI string.

```shell Examples of valid URLs
# Basic url
http://example.com/full/path/to/file.csv

# HTTP Basic Auth
http://name:passwd@example.com/full/path/to/file.csv

# FTP with authentication
ftp://name:passwd@example.com:21/full/path/to/file.csv
```

```text Contents of file.csv
id,email,name
"12345","support@neverbounce.com","Fred McValid"
"12346","invalid@neverbounce.com","Bob McInvalid"
```

### Supplied Data

Supplying the data directly gives you the option to dynamically create email lists on the fly rather than having to write to a file. `input` will accept an array of objects or arrays that contain the email, as well as any ancillary data you wish to associate with the email (e.g. user IDs, names, contact information).

If the data is supplied as an object, the key names will be used for the column headers. If the data is supplied as an array, column headers will be omitted. Below is a sample of what each looks like in JSON.

> 🚧 Our API enforces a max request size of 25 Megabytes. If you surpass this limit you'll receive a `413 Entity Too Large` error from the server. For payloads that exceed 25 Megabytes we suggest using the `remote_url` method or removing any ancillary data sent with the emails.

```json Object
[
    {
        "id": 12345,
        "email": "support@neverbounce.com",
        "name": "Fred McValid"
    },
    {
        "id": 12346,
        "email": "invalid@neverbounce.com",
        "name": "Bob McInvalid"
    }
]
```
```json Array
[
    [
        12345,
        "support@neverbounce.com",
        "Fred McValid"
    ],
    [
        12346,
        "invalid@neverbounce.com",
        "Bob McInvalid"
    ]
]
```

## Manual Reviews

Our manual review process allows us to take a second look at jobs that have a high rate of unknowns. Often we can re-run lists at a later time or under specific configurations to further resolve these unknowns. This requires a member of our team to perform these reviews so they only occur during our normal business hours.

While this works well for most dashboard users, this isn't always optimal for API users who programmatically access their lists. Starting in `4.2` we've introduced the `allow_manual_review` to allow users to opt-into this featured when creating their API jobs.

If a `allow_manual_review` is enabled, your job may take up to 1 business day to be released if it falls into the manual review queue. The job status will include the `under_review` job status if it's in this queue.

## Callback URL and Headers

To enable callbacks to your application you must supply an accessible URL in the `callback_url` parameter. This URL should start with either `http://` or `https://` and be accessible over the internet. You can supply basic authentication credentials directly in the URL.

```text Valid Callback URLs
# Basic url
https://example.com/webhooks/neverbounce

# HTTPS with Basic Auth
https://name:passwd@example.com/webhooks/neverbounce
```

You can also specific headers to include in the callback requests with the `callback_headers` parameter. You can use these to set an authorization token or internal reference for the job.

```json
curl --request POST\
  --header "Content-Type: application/json"\
  --url https://api.neverbounce.com/v4.2/jobs/create\
  --data '{
    "key": {api_key},
    "input_location": "supplied",
    "filename": "SampleNeverBounceAPI.csv",
    "auto_start": true,
    "auto_parse": true,
    "callback_url": "https://example.com/callbacks/neverbounce",
    "callback_headers": {
        "X-My-Token": "abc123"
    }, 
    "input": [
        [
            "support@neverbounce.com",
            "Fred McValid"
        ],
        [
            "invalid@neverbounce.com",
            "Bob McInvalid"
        ]
    ]
}'
```

For more information about callbacks and a list of supported events see [job callbacks](https://developers.neverbounce.com/reference/job-callbacks).

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "neverbounce-api",
    "version": "4.2"
  },
  "servers": [
    {
      "url": "https://api.neverbounce.com/v4.2"
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "type": "apiKey",
        "in": "query",
        "name": "key"
      }
    }
  },
  "security": [
    {
      "sec0": []
    }
  ],
  "paths": {
    "/jobs/create": {
      "post": {
        "summary": "/create",
        "description": "",
        "operationId": "jobs-create",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "input_location",
                  "input"
                ],
                "properties": {
                  "input_location": {
                    "type": "string",
                    "description": "The type of input being supplied. Accepted values are \"remote_url\" and \"supplied\"."
                  },
                  "input": {
                    "type": "string",
                    "description": "The input to be verified",
                    "format": "json"
                  },
                  "auto_parse": {
                    "type": "boolean",
                    "description": "Should we begin parsing the job immediately? (default: false)",
                    "default": false
                  },
                  "auto_start": {
                    "type": "boolean",
                    "description": "Should we run the job immediately after being parsed? (default: false)",
                    "default": false
                  },
                  "run_sample": {
                    "type": "boolean",
                    "description": "Should this job be run as a sample? (default: false)",
                    "default": false
                  },
                  "filename": {
                    "type": "string",
                    "description": "This will be what's displayed in the dashboard when viewing this job"
                  },
                  "request_meta_data": {
                    "type": "object",
                    "description": "Miscellanious request meta data",
                    "properties": {
                      "leverage_historical_data": {
                        "type": "boolean",
                        "description": "Control historical data usage, set to false to use real-time only verification",
                        "default": true
                      }
                    }
                  },
                  "allow_manual_review": {
                    "type": "boolean",
                    "description": "Denotes whether or not the job should be allowed to fall into manual review",
                    "default": false
                  },
                  "callback_url": {
                    "type": "string",
                    "description": "An optional URL that we should send events to during the lifecycle of the job"
                  },
                  "callback_headers": {
                    "type": "string",
                    "description": "An optional array of headers that should be included when sending events to the callback_url",
                    "format": "json"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n  \"status\": \"success\",\n  \"job_id\": 150970,\n  \"execution_time\": 712\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "success"
                    },
                    "job_id": {
                      "type": "integer",
                      "example": 150970,
                      "default": 0
                    },
                    "execution_time": {
                      "type": "integer",
                      "example": 712,
                      "default": 0
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "400",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          }
        },
        "deprecated": false,
        "x-readme": {
          "code-samples": [
            {
              "language": "curl",
              "code": "# x-www-form-urlencoded request w/ remote_url input\ncurl --request POST\\\n  --url https://api.neverbounce.com/v4.2/jobs/create\\\n  --data key={api_key}\\\n  --data input_location='remote_url'\\\n  --data filename='SampleNeverBounceAPI.csv'\\\n  --data auto_parse=true\\\n  --data auto_start=true\\\n  --data allow_manual_review=false\\\n  --data input='https://mydomain.com/my_file.csv'\\\n  --data callback_url='https://mydomain.com/callbacks/neverbounce'\\\n  --data 'callback_headers[X-My-Token]=123abc'",
              "name": "cURL Remote URL"
            },
            {
              "language": "curl",
              "code": "# x-www-form-urlencoded request w/ supplied data\ncurl --request POST\\\n  --url https://api.neverbounce.com/v4.2/jobs/create\\\n  --data key={api_key}\\\n  --data input_location='supplied'\\\n  --data filename='SampleNeverBounceAPI.csv'\\\n  --data auto_parse=true\\\n  --data auto_start=true\\\n  --data allow_manual_review=false\\\n  --data 'input[0][0]=support%40neverbounce.com'\\\n  --data 'input[0][1]=Fred%20McValid'\\\n  --data 'input[1][0]=invalid%40neverbounce.com'\\\n  --data 'input[1][1]=Bob%20McInvalid'\n  --data callback_url='https://mydomain.com/callbacks/neverbounce'\\\n  --data 'callback_headers[X-My-Token]=123abc'\n  \n# JSON encoded request w/ supplied data\ncurl --request POST\\\n  --header \"Content-Type: application/json\"\\\n  --url https://api.neverbounce.com/v4.2/jobs/create\\\n  --data '{\n    \"key\": {api_key},\n    \"input_location\": \"supplied\",\n    \"filename\": \"SampleNeverBounceAPI.csv\",\n    \"auto_start\": true,\n    \"auto_parse\": true,\n    \"allow_manual_review\": false,\n    \"input\": [\n        [\n            \"support@neverbounce.com\",\n            \"Fred McValid\"\n        ],\n        [\n            \"invalid@neverbounce.com\",\n            \"Bob McInvalid\"\n        ]\n    ],\n    \"callback_url\": \"https://mydomain.com/callbacks/neverbounce\",\n    \"callback_headers\": {\n    \t\"X-My-Token\": \"123abc\"\n    }\n}'",
              "name": "cURL Supplied Data"
            },
            {
              "language": "php",
              "code": "<?php\n\n// Set API key\n\\NeverBounce\\Auth::setApiKey($api_key);\n\n// Build json\n$arr = [\n    [\n        'support@neverbounce.com',\n        'Fred McValid'\n    ],\n    [\n        'invalid@neverbounce.com',\n        'Bob McInvalid'\n    ]\n];\n\n// Make a new job with the supplied data\n$job = \\NeverBounce\\Jobs::create(\n  $arr, // input\n  \\NeverBounce\\Jobs::SUPPLIED_INPUT, // Either `supplied` or `remote_url`\n  'SampleNeverBounceAPI.csv', // Friendly name that can be used to identify job\n  false, // Run as sample\n  true, // Auto parse\n  true, // Auto start,\n  false, // Allow manual review\n  null, // Callback URL\n  null // Callback Headers\n);\n"
            },
            {
              "language": "javascript",
              "code": "// Initialize NeverBounce client\nconst client = new NeverBounce({apiKey: myApiKey});\n\n// Verify a list of emails\nclient.jobs.create(\n    [\n        {\n            'id': '12345',\n            'email': 'support@neverbounce.com',\n            'name': 'Fred McValid'\n        },\n        {\n            'id': '12346',\n            'email': 'invalid@neverbounce.com',\n            'name': 'Bob McInvalid'\n        }\n    ],\n    'supplied', // Either `supplied` or `remote_url`\n    'Created from Array.csv', // Friendly name that can be used to identify job\n  \tfalse, // Run sample\n  \ttrue, // Auto parse\n    true // Auto run,\n    false, // Allow manual review\n    null, // Callback URL\n    null // Callback Headers\n).then(\n    resp => // Handle success response\n    err => // Handle error response\n);",
              "name": "NodeJs"
            },
            {
              "language": "python",
              "code": "import neverbounce_sdk\n\n# Create sdk client\nclient = neverbounce_sdk.client(api_key='api_key')\n\n# Create array of data\ninputData = [\n  {\n    'id': '12345',\n    'email': 'support@neverbounce.com',\n    'name': 'Fred McValid'\n  },\n  {\n    'id': '12346',\n    'email': 'invalid@neverbounce.com',\n    'name': 'Bob McInvalid'\n  }\n]\n\n# Create Job\nresp = client.jobs_create(\n  input=inputData,\n  filename=\"Created from Python Wrapper.csv\",\n  # auto_parse=True,\n  # auto_start=True,\n  # as_sample=False,\n  # from_url=False,\n  # allow_manual_review=None,\n  # callback_url=None\n  # callback_headers=None\n)"
            },
            {
              "language": "go",
              "code": "// Instantiate wrapper\nclient := neverbounce.New(\"api_key\")\n\n// Build data map\ncreateData := map[int]interface{}{}\ncreateData[0] = map[string]interface{}{\n  \"id\":    12345,\n  \"email\": \"support@neverbounce.com\",\n  \"name\":  \"Bob McValid\",\n}\ncreateData[1] = map[string]interface{}{\n  \"id\":    12346,\n  \"email\": \"invalid@neverbounce.com\",\n  \"name\":  \"Fred McInvalid\",\n}\n\n// Create a job from supplied data\njobInfo, err := client.Jobs.CreateFromSuppliedData(&nbModels.JobsCreateSuppliedDataRequestModel{\n  SuppliedData: createData,\n  AutoParse:    false,\n  AutoRun:      false,\n  RunSample:    false,\n  FileName:     \"Created from Golang.csv\",\n  AllowManualReview: false,\n  // CallbackURL: string\n  // CallbackHeaders: map[string]interface{}\n})\nif err != nil {\n  panic(err)\n}\n\n// Create a job from a remote URL\njobInfo, err := client.Jobs.CreateFromRemoteURL(&nbModels.JobsCreateRemoteURLRequestModel{\n  RemoteURL: \"https://example.com/file.csv\",\n  AutoParse: true,\n  AutoRun:   false,\n  RunSample: false,\n  FileName:  \"Created from Golang.csv\",\n  AllowManualReview: false,\n  // CallbackURL: string\n  // CallbackHeaders: map[string]interface{}\n})\nif err != nil {\n  panic(err)\n}"
            },
            {
              "language": "ruby",
              "code": "# Instantiate API client\nclient = NeverBounce::API::Client.new(api_key: \"api_key\")\n\n# Create job with supplied input\nresp = client.jobs_create(\n  supplied_input: [\n    [\"alice@isp.com\", \"Alice Roberts\"], \n    [\"bob.smith@gmail.com\", \"Bob Smith\"]\n  ]\n)\n\n# Create job with remote file\nresp = client.jobs_create(remote_input: \"http://example.com/emails.csv\", filename: \"emails.csv\")"
            },
            {
              "language": "csharp",
              "code": "// Create SDK object\nvar sdk = new NeverBounceSdk(\"api_key\");\n\n/**\n * Create a job using supplied data\n */\n\n// Create supplied data model\nvar model = new JobCreateSuppliedDataRequestModel();\nmodel.filename = \"Created From dotNET.csv\";\nmodel.auto_parse = true;\nmodel.auto_start = false;\nmodel.input = new List<object>();\nmodel.input.Add(new {id = \"3\", email = \"support@neverbounce.com\", name = \"Fred McValid\"});\nmodel.input.Add(new {id = \"4\", email = \"invalid@neverbounce.com\", name = \"Bob McInvalid\"});\nmodel.allow_manual_review = false;\n//model.callback_url = \"https://example.com/callback/neverbounce\";\n//model.callback_headers = Dictionary<string, string>\n\n// Create job from supplied data\nJobCreateResponseModel resp = await sdk.Jobs.CreateFromSuppliedData(model);\n\n/**\n * Create a job using a remote url\n */\n\n// Create remote url model\nvar model2 = new JobCreateRemoteUrlRequestModel();\nmodel.filename = \"Created From dotNET.csv\";\nmodel.auto_parse = true;\nmodel.auto_start = false;\nmodel.input = \"https://example.com/file.csv\";\nmodel.allow_manual_review = false;\n//model.callback_url = \"https://example.com/callback/neverbounce\";\n//model.callback_headers = Dictionary<string, string>\n\n// Create job from remote url\nJobCreateResponseModel resp2 = await sdk.Jobs.CreateFromRemoteUrl(model);",
              "name": ".NET"
            }
          ],
          "samples-languages": [
            "curl",
            "php",
            "javascript",
            "python",
            "go",
            "ruby",
            "csharp"
          ]
        }
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```