Purlem API

The Purlem API is organized around REST, uses JSON for serialization and HTTP basic authentication. The API allows for basic CRUD operations on campaigns, contacts and results.

Authentication

You authenticate to the Purlem API by providing your User ID and API token in the request throught HTTP basic authentication. You can find both your User ID and API Token in your Purlem dashboard under My Account.

In curl, that looks like:

curl -u user:token

Request

All URLs start with https://purlapi.com/v1/. The path is prefixed with the the API version.

To make a request for all the results in a campaign, you'd append the campaign's index path to the base url to form something like /results/{CAMPAIGN ID}. In curl, that looks like:

curl -u user:token https://purlapi.com/v1/results/{CAMPAIGN ID}

To add,update or delete something, it's the same deal except you also have to POST the data. To add a contact it would look like:

curl -u user:token
  -X POST 
  --data "campaignID={CAMPAIGN ID}&firstName=Bob&lastName=Jones" 
  http://purlapidev.com/v1/contacts/add

That's all!

Response

All responses will use JSON for serialization of data. The response for adding a contact would be something like:

{
"type":"contact.created",
"object":"event",
"timestamp":"2012-12-21 01:01:01",
"data":{
  "ID":"{CONTACT ID}",
	"userID":"{USER ID}",
	"campaignID":"{CAMPAIGN ID}",
	"firstName":"Bob",
	"lastName":"Jones",
	"purl":"http://domain.com/Bob.Thomas"
	}
}

Errors

If there is a problem with your request you will receive 4xx error, along with JSON data describing the error. An error response may look like:

{"message":"Bad Authentication data","code":400}

Limiting

You can perform up to 100 requests per 1 hour period for the same account.

Available Resources

Get Contact

/v1/contacts/{CONTACT ID}

curl -u user:token  https://purlapi.com/v1/contacts/123

Get By Contact

/v1/contacts/get_by/{FIELD}/{DATA}

curl -u user:token  https://purlapi.com/v1/contacts/get_by/purl/BobThomas

Get Many By Contact

/v1/contacts/get_many_by/{FIELD}/{DATA}

curl -u user:token  https://purlapi.com/v1/contacts/get_many_by/purl/BobThomas

Get Many Where Exist

/v1/contacts/get_many_where_exists/{FIELD}

curl -u user:token  https://purlapi.com/v1/contacts/get_many_where_exists/email

Add Contact /v1/contacts/add

curl -u user:token -X POST --data "campaignID=1051&firstName=Bob&lastName=Jones https://purlapi.com/v1/contacts/add

Update Contact

/v1/contacts/update

curl -u user:token -X POST --data "contactID=123&company=XYZCorp" https://purlapi.com/v1/contacts/update

Delete Contact

/v1/contacts/delete/{CONTACT ID}

curl -u user:token -X POST https://purlapi.com/v1/contacts/delete/123

Get All Campaigns

/v1/campaigns

curl -u user:token  https://purlapi.com/v1/campaigns

Get All Campaign Contacts

/v1/campaigns/{CAMPAIGN ID}/contacts

curl -u user:token  https://purlapi.com/v1/campaigns/1/contacts

Get All Campaign Contacts Where Exist

/v1/campaigns/{CAMPAIGN ID}/contacts_where_exists/{FIELD}

curl -u user:token  https://purlapi.com/v1/campaigns/1/contacts_where_exists/email

Get All Campaign Contacts Since

/v1/campaigns/{CAMPAIGN ID}/contacts/since/{MINUTES}

curl -u user:token  https://purlapi.com/v1/campaigns/1/contacts/since/5

Get Campaign Fields

/v1/campaigns/{CAMPAIGN ID}/get_fields

curl -u user:token  https://purlapi.com/v1/campaigns/1/get_fields

Get Campaign

/v1/campaigns/{CAMPAIGN ID}

curl -u user:token  https://purlapi.com/v1/campaigns/1

Add instantPURL Campaign

/v1/campaigns/add/instantpurl

curl -u user:token -X POST --data "name=My-Campaign&template=default" https://purlapi.com/v1/campaigns/add/instantpurl

Add FTP Campaign

/v1/campaigns/add/ftp

curl -u user:token -X POST --data "name=My-Campaign&template=default&url=http://mydomain.com&ftp_server=ftp.mydomain.com&ftp_username=myusername&ftp_password=mypassword&ftp_path=public_html" https://purlapi.com/v1/campaigns/add/ftp

Update Campaign

/v1/campaigns/update

curl -u user:token -X POST --data "name=New-Name&campaignID=1" https://purlapi.com/v1/campaigns/update

Delete Campaign

/v1/campaigns/delete/{CAMPAIGN ID}

curl -u user:token -X POST https://purlapi.com/v1/campaigns/delete/1

Get Campaign's Results

/v1/results/{CAMPAIGN ID}

curl -u user:token https://purlapi.com/v1/results/1

Get Campaign's Results Since

/v1/results/{CAMPAIGN ID}/since/{MINUTES}

curl -u user:token https://purlapi.com/v1/results/1/since/5

Get Contact's Results

/v1/results/get_contact/{CONTACT ID}

curl -u user:token https://purlapi.com/v1/results/get_contact/1

Delete Result

/v1/results/delete/{RESULT ID}

curl -u user:token -X POST https://purlapi.com/v1/results/delete/1523

Get All Clients

/v1/clients

curl -u user:token  https://purlapi.com/v1/clients

Get Client

/v1/campaigns/{CLIENT ID}

curl -u user:token  https://purlapi.com/v1/clients/1

Add Client

/v1/campaigns/add/client

curl -u user:token -X POST --data "name=ClientName&username=user&password=pass&planID=2" https://purlapi.com/v1/clients/add

Update Client

/v1/clients/update

curl -u user:token -X POST --data "clientID=1name=ClientName&username=user&password=pass&planID=2" https://purlapi.com/v1/clients/update

Delete Client

/v1/clients/delete/{CLIENT ID}

curl -u user:token -X POST https://purlapi.com/v1/clients/delete/1

Get Customfield

/v1/customfields/get/{CUSTOMFIELD ID}

curl -u user:token  https://purlapi.com/v1/customfields/get/123