REST Resources

This document contains a description of the resources available via HTTPS. All resources are RESTful and represented using JSON. Authentication is performed using HTTP Basic Auth.

Base Resource Path Description Reference
/batches List, create, get, update, delete batches, and add a batch record Batch
/files List and create batch files Batch File

If you are getting unexpected responses from the API, see the errors section.

Batches

The /batches resource is used to work with batches.

Method Resource Description
GET /batches List all batches
GET /batches/{id} Get a batch
POST /batches Create a batch
PUT /batches/{id} Update a batch
DELETE /batches/{id} Delete a batch
POST /batches/{id}/record Add a batch record

^ back to top

List all batches

Get the list of all batches.

Resource Information

Method GET
URL https://batch.leadconduit.com/batches
MIME Type application/json
Status Code 200
Authenticated? Yes
Reference Batch

^ back to top

Query parameters

Parameter Description Type
after_id Return only batches that were created after the one with this ID (exclusive) BSON ID
before_id Return only batches that were created before the one with this ID (exclusive) BSON ID
start Return only batches that were created at or after this time Timestamp
end Return only batches that were created at or before this time Timestamp
sort The sort direction (asc or desc, default desc) String

Example

The below example shows how to get a list of all batches using the curl utility. The response body is truncated for brevity. See the batch reference for full details.

$ curl -v -X GET -uX:1234567890 -H 'Accept: application/json' https://batch.leadconduit.com/batches

> GET /batches HTTP/1.1
> Authorization: Basic MTIzNDU2Nzg5MA==
> User-Agent: curl/7.37.1
> Host: batch.leadconduit.com
> Accept: application/json
>
< HTTP/1.1 200 OK
< vary: Accept, Accept-Encoding
< content-type: application/json
< date: Mon, 17 Aug 2015 19:59:14 GMT
< connection: keep-alive
< transfer-encoding: chunked
<
[
  {
    "id": "55d1f41b976c0bfb67e7a836",
    "name": "My Batch",
    ...
  },
  {
    "id": "55d23db2969983686ab09487",
    "name": "My Favorite Batch",
    ...
  }
]

^ back to top

Create a batch

Create a new batch, adding it to the list of all batches in the account.

Resource Information

Method POST
URL https://batch.leadconduit.com/batches
MIME Type application/json
Status Code 201
Authenticated? Yes
Reference Batch

^ back to top

Example

The below example shows how to create a new batch using the curl utility. The response body is truncated for brevity. See the batch reference for full details.

$ curl -v -X POST \
       -uX:1234567890 \
       -H'Content-Type: application/json' \
       -H'Accept: application/json' \
       -d@batch.json \
       https://batch.leadconduit.com/batches

> POST /batches HTTP/1.1
> Authorization: Basic MTIzNDU2Nzg5MA==
> User-Agent: curl/7.37.1
> Host: batch.leadconduit.com
> Accept: application/json
> Content-Type: application/json

< HTTP/1.1 201 Created
< vary: Accept, Accept-Encoding
< content-type: application/json; charset=utf-8
< content-length: 1279
< date: Mon, 17 Aug 2015 14:47:55 GMT
< connection: keep-alive
<
{
  "id": "55d1f41b976c0bfb67e7a836",
  "name": "My Batch",
  ...
}

^ back to top

Update a batch

Update an existing batch.

Resource Information

Method PUT
URL https://batch.leadconduit.com/batches/{id}
MIME Type application/json
Status Code 200
Authenticated? Yes
Reference Batch

^ back to top

Example

The below example shows how to update an existing batch using the curl utility. The response body is truncated for brevity. See the batch reference for full details.

$ curl -v -X PUT \
       -uX:1234567890 \
       -H'Content-Type: application/json' \
       -H'Accept: application/json' \
       -d@batch.json \
       https://batch.leadconduit.com/batches/55d1f41b976c0bfb67e7a836

> PUT /batches/55ce4e5538b57a7508b034c5 HTTP/1.1
> Authorization: Basic MTIzNDU2Nzg5MA==
> User-Agent: curl/7.37.1
> Host: batch.leadconduit.com
> Accept: application/json
> Content-Type: application/json

< HTTP/1.1 200 OK
< vary: Accept, Accept-Encoding
< content-type: application/json; charset=utf-8
< content-length: 1279
< date: Mon, 17 Aug 2015 14:51:55 GMT
< connection: keep-alive
<
{
  "id": "55d1f41b976c0bfb67e7a836",
  "name": "My Batch",
  ...
}

^ back to top

Get a batch

Fetch a single batch.

Resource Information

Method GET
URL https://batch.leadconduit.com/batches/{id}
MIME Type application/json
Status Code 200
Authenticated? Yes
Reference Batch

^ back to top

Query parameters

None.

Example

The below example shows how to get an existing batch using the curl utility. The response body is truncated for brevity. See the batch reference for full details

$ curl -v -X GET \
       -uX:1234567890 \
       -H'Accept: application/json' \
       https://batch.leadconduit.com/batches/55ce4e5538b57a7508b034c5

> GET /batches/55ce4e5538b57a7508b034c5 HTTP/1.1
> Authorization: Basic MTIzNDU2Nzg5MA==
> User-Agent: curl/7.37.1
> Host: batch.leadconduit.com
> Accept: application/json
>
< HTTP/1.1 200 OK
< vary: Accept, Accept-Encoding
< content-type: application/json; charset=utf-8
< content-length: 1269
< etag: W/"7tv5tV52dBzQjrhhQt4PYg=="
< date: Fri, 14 Aug 2015 20:12:59 GMT
< connection: keep-alive
<
{
  "id": "55ce4e5538b57a7508b034c5",
  "name": "My first batch",
  ...
}

^ back to top

Delete a batch

Delete an existing batch. Once a batch is deleted it will no longer accept leads. Attempting to submit leads to a deleted batch will result in an HTTP 404.

Query parameters

Parameter Description Type
purge Determines whether to remove all references to this batch, including past deliveries, or to leave past batch files available to download Boolean

Resource Information

Method DELETE
URL https://batch.leadconduit.com/batches/{id}
MIME Type application/json
Status Code 200
Authenticated? Yes
Reference Batch

^ back to top

Example

The below example shows how to delete an existing batch using the curl utility. The response body is truncated for brevity. See the batch reference for full details.

$ curl -X DELETE -uX:1234567890 https://batch.leadconduit.com/batches/55ce4e5538b57a7508b034c5

> DELETE /batchs/55ce4e5538b57a7508b034c5 HTTP/1.1
> Authorization: Basic MTIzNDU2Nzg5MA==
> User-Agent: curl/7.37.1
> Host: batch.leadconduit.com
> Accept: application/json
>
< HTTP/1.1 200 OK
< vary: Accept, Accept-Encoding
< content-type: application/json; charset=utf-8
< content-length: 1269
< etag: W/"7tv5tV52dBzQjrhhQt4PYg=="
< date: Fri, 14 Aug 2015 20:12:59 GMT
< connection: keep-alive
<

^ back to top

Add a batch record

Create a new batch record to a specific batch.

Resource Information

Method POST
URL https://batch.leadconduit.com/batches/{id}/records
MIME Type application/json
Status Code 201
Authenticated? Yes
Reference Batch

^ back to top

Example

The below example shows how to create a new batch record using the curl utility. See the batch record reference for full details.

$ curl -v -X POST \
       -uX:1234567890 \
       -H'Content-Type: application/json' \
       -H'Accept: application/json' \
       -d@batch_record.json \
       https://batch.leadconduit.com/batches/55d1f41b976c0bfb67e7a836/records

> POST /batches/55d1f41b976c0bfb67e7a836/records HTTP/1.1
> Authorization: Basic MTIzNDU2Nzg5MA==
> User-Agent: curl/7.37.1
> Host: batch.leadconduit.com
> Accept: application/json
> Content-Type: application/json

< HTTP/1.1 201 Created
< vary: Accept, Accept-Encoding
< content-type: application/json; charset=utf-8
< content-length: 21
< access-control-allow-credentials: true
< access-control-allow-origin: *
< date: Mon, 17 Aug 2015 14:47:55 GMT
< connection: keep-alive
<
{
  "outcome": "success"
}

Other possible values for outcome include failure (when inbound is set to false for the batch) or error for authentication issues or server errors. The reason property is included for failures and errors to provide additional details.

^ back to top

Batch Files

The /files resource is used to work with batch files.

Method Resource Description
GET /files List all batch files
POST /files Create a batch file
GET /files/{id} Get a batch file
GET /files/{id}/download Download a batch file

^ back to top

List all batch files

Get the list of all batch files created for this account.

Query parameters

Parameter Description Type
after_id Return only files that were created after the one with this ID (exclusive) BSON ID
before_id Return only files that were created before the one with this ID (exclusive) BSON ID
start Return only files that were created at or after this time Timestamp
end Return only files that were created at or before this time Timestamp
limit The maximum number of events to return (maximum limit is 100, default 100) Integer
sort The sort direction (asc or desc, default desc) String

Resource Information

Method GET
URL https://batch.leadconduit.com/files
MIME Type application/json
Status Code 200
Authenticated? Yes
Reference Batch File

Normally to retrieve a range of events either before_id and after_id are used together or start and end are used together. However, if both before_id and end are specified, the lesser of the two will be used. If both after_id and start are specified, the greater of the two will be used.

^ back to top

Example

$ curl -X GET -uX:1234567890 https://batch.leadconduit.com/files

> GET /files HTTP/1.1
> Authorization: Basic MTIzNDU2Nzg5MA==
> User-Agent: curl/7.37.1
> Host: batch.leadconduit.com
> Accept: application/json
>
< HTTP/1.1 200 OK
< vary: Accept, Accept-Encoding
< content-type: application/json; charset=utf-8
< content-length: 123
< etag: W/"7tv5tV52dBzQjrhhQt4PYg=="
< date: Fri, 14 Aug 2015 20:15:12 GMT
< connection: keep-alive
<

[
  {
    "id": "56f3510ee3d4b787f8befccd",
    "name": "BatchFile.csv",
    ...
  },
  {
    ...
  }
]

^ back to top

Create a batch file

Create a new batch file, immediately delivering it via the method specified. A pre-existing batch configuration can be used to generate the file, or an entirely new configuration can be supplied.

Resource Information

Method POST
URL https://batch.leadconduit.com/files
MIME Type application/json
Status Code 201
Authenticated? Yes
Reference Batch File

^ back to top

Example

The below example shows how to create a new batch file using the curl utility. The response body is truncated for brevity. See the batch file reference for full details.

$ curl -v -X POST \
       -uX:1234567890 \
       -H'Content-Type: application/json' \
       -H'Accept: application/json' \
       -d@batch_file.json \
       https://batch.leadconduit.com/files

> POST /files HTTP/1.1
> Authorization: Basic MTIzNDU2Nzg5MA==
> User-Agent: curl/7.37.1
> Host: batch.leadconduit.com
> Accept: application/json
> Content-Type: application/json

< HTTP/1.1 201 Created
< vary: Accept, Accept-Encoding
< content-type: application/json; charset=utf-8
< content-length: 1279
< date: Mon, 17 Aug 2015 14:47:55 GMT
< connection: keep-alive
<
{
  "id": "55d1f41b976c0bfb67e7a836",
  "name": "My Batch File",
  ...
}

^ back to top

Get a batch file

Fetch a single batch file.

Resource Information

Method GET
URL https://batch.leadconduit.com/file/{id}
MIME Type application/json
Status Code 200
Authenticated? Yes
Reference Batch File

^ back to top

Query parameters

None.

Example

The below example shows how to get an existing batch file using the curl utility. The response body is truncated for brevity. See the batch file reference for full details

$ curl -v -X GET \
       -uX:1234567890 \
       -H'Accept: application/json' \
       https://batch.leadconduit.com/files/55ce4e5538b57a7508b034c5

> GET /files/55ce4e5538b57a7508b034c5 HTTP/1.1
> Authorization: Basic MTIzNDU2Nzg5MA==
> User-Agent: curl/7.37.1
> Host: batch.leadconduit.com
> Accept: application/json
>
< HTTP/1.1 200 OK
< vary: Accept, Accept-Encoding
< content-type: application/json; charset=utf-8
< content-length: 1269
< etag: W/"7tv5tV52dBzQjrhhQt4PYg=="
< date: Fri, 14 Aug 2015 20:12:59 GMT
< connection: keep-alive
<
{
  "id": "55ce4e5538b57a7508b034c5",
  "name": "MyFirstBatchFile.csv",
  ...
}

^ back to top

Errors

Things can go wrong when using the API. This reference table explains common error outcomes and what they mean. If you receive an error code that is not listed here, please contact support@activeprospect.com.

HTTP Status Name Description
401 Unauthorized The API key is missing, incorrect, or specified incorrectly
403 Forbidden An attempt has been made to modify a resource which cannot be modified
404 Not Found The resource being requested does not exist
406 Not Acceptable An unsupported MIME type has been requested in the Accept header
409 Conflict The request to update a resource has failed because a more recent version exists
415 Unsupported Media Type The request contains a request body of an unsupported MIME type
422 Unprocessable Entity The JSON in the request body is incorrect, probably caught by validation
503 Service Unavailable The API service is currently unavailable, probably due to high load

^ back to top

Validation

The server will validate calls to create or update a resource. If you attempt to make a change that fails validation, you will receive an HTTP 422. The body of the response maps the error messages to the original JSON document submitted.

^ back to top