Requests - URL Formats

The Public API format supports authentication via API key authentication. It has the format:

Request

https://{hostname}/{api-version}/{path}?[parameters]

For the Public API format, the components of the URL are:

• hostname: api.bouncify.io
• api-version: The API versions required to use in the path, for example v1.
• path: The api method you are requesting, including any path parameters — for example /v1/bulk/{job_id}.
• parameters: The query parameters, supplied after the ? as key=value pairs joined with & — for example ?apikey=YOUR_API_KEY.

caution

API endpoints listed in this doc will work on HTTPS. It does not support HTTP.

Where each parameter goes

A request can carry parameters in three places. Which one depends on the parameter — they are not interchangeable, and putting one in the wrong place fails:

What is wrong with the request	Response
A required path parameter is missing from the URL	400 Invalid request. Required Id.
apikey is missing entirely	400 Invalid request. Required API key.
apikey is present but not a valid 32-character key	401 Invalid API key

Path parameters

Part of the URL path. They are substituted positionally and take no key= — job_id is appended to the resource, not added as a query string:

PATCH https://api.bouncify.io/v1/bulk/{job_id}
                              ^^^^^^^^ path parameter

Query parameters

Supplied after the ? as key=value pairs joined with &. apikey is always a query parameter on every v1 endpoint — there is no header or body form of it. It is exactly 32 characters.

PATCH https://api.bouncify.io/v1/bulk/{job_id}?apikey=YOUR_API_KEY
                                              ^^^^^^^^^^^^^^^^^ query parameter

Body parameters

Sent as a JSON (or multipart, for uploads) request body on POST and PATCH. They never appear in the URL.

{ "action": "start" }

Which is which

Endpoint	Path parameters	Query parameters	Body
POST /v1/bulk	—	apikey	multipart CSV, or JSON emails
PATCH /v1/bulk/{job_id}	job_id	apikey	{ "action": "start" }
GET /v1/bulk/{job_id}	job_id	apikey	—
DELETE /v1/bulk/{job_id}	job_id	apikey	—
POST /v1/download	—	jobId, apikey	{ "filterResult": [ … ] }
GET /v1/verify	—	email, apikey, timeout	—
GET /v1/info	—	apikey	—

job_id (bulk) is not jobId (download)

The bulk endpoints take job_id — snake_case, in the path. The download endpoint takes jobId — camelCase, in the query string. They are not interchangeable in name or location; the wrong one returns 400 Invalid request. Required Id. for bulk, or 403 Expected field params.query.jobId not available for download.

Example

Example Request

https://api.bouncify.io/v1/verify?apikey=YOUR_API_KEY&email=some@gmail.com