No description, website, or topics provided.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
README.md

README.md

Tend API

Organized around REST, using JSON for serialization and HTTP Basic Auth for authentication.

Authentication

Authenticate into the Tend API by providing our username and password.

Via Browser:

https://tend.io/api/v1/contacts

And enter your Tend username & password when prompted.

With CURL:

curl -u user:pass https://tend.io/api/v1/contacts

All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

Pagination

Most collection APIs paginate their results. The first request returns up to 50 records. Check the next page for more results by adding &page=2, then &page=3, and so on until you get an empty response.

Errors

Tend uses conventional HTTP response codes to indicate success or failure of an API request.

200 OK - Everything worked as expected.

400 Bad Request - Often missing a required parameter.

401 Unauthorized - Authentication failed.

402 Request Failed - Parameters were valid but request failed.

404 Not Found - The requested item doesn't exist.

500, 502, 503, 504 Server errors - something went wrong on Tend's end.

Rate limiting

You can perform up to 10,000 requests per 5 minute period from the same IP address for the same account. If you exceed this limit, you'll get a 429 Too Many Requests response for subsequent requests.

Methods

Contacts

Get all contacts

  • GET /contacts will return all of the contacts in the account.
curl -u user:pass https://tend.io/api/v1/contacts
{
    "id": 123,
    "ip": "123.12.12.123",
    "name": "Marty Thomas",
    "firstName": "Marty",
    "lastName": "Thomas",
    "email": "marty@tend.io",
    "company": {
        "id": 123,
        "name": "Tend",
        "website": "https://www.tend.io",
        "phone": "123-123-1234",
        "address": "2 N. LaSalle St.",
        "city": "Chicago",
        "state": "IL",
        "zip": "",
        "country": ""
    },
    "title": "Co-Founder",
    "bio": "Co-Founder at Tend. Founder & Developer at Purlem. Husband to my biggest cheerleader. And father to the new loves of my life.",
    "website": "https://www.tend.io",
    "address": "2 N. LaSalle St.",
    "city": "Chicago",
    "state": "IL",
    "zip": "",
    "country": "",
    "photo": "https://d2ojpxxtu63wzl.cloudfront.net/static/0cf998559aa4eae658ff31c0b338f155_344b70e63894af453574c5e548d38496ca282ca605c6225d10e2856518bf570c",
    "facebook": "",
    "twitter": "http://twitter.com/martyjthomas",
    "linkedin": "https://www.linkedin.com/in/martinjthomas",
    "a_customfield_id": "the custom field value",
    "activity": {
        "sessions": 1,
        "visits": 6
    },
    "pages": ["test.com","test.com/blog"],
    "entrypages": ["test.com","test.com/blog"],
    "segments": ["Customers","Hot Lead"],
    "events": ["Stripe Charge"],
    "referrers": ["Google","Facebook"],
    "params": {
        "campaignids": ["1234","5678"],
        "adgroupids": ["1234","5678"],
        "networks": ["foo","bar"],
        "creatives": ["foo","bar"],
        "keywords": ["foo","bar"],
        "utm_campaigns": ["foo","bar"],
        "utm_terms": ["foo","bar"],
        "utm_mediums": ["foo","bar"],
        "utm_sources": ["foo","bar"],
        "utm_contents": ["foo","bar"]
    },
},
{
    "id": 456,
    "ip": "123.12.12.123",
    "name": "Ryan Evans",
    "firstName": "Ryan",
    "lastName": "Evans",
    "email": "ryan@tend.io",
    "company": {
        "id": 123,
        "name": "Tend",
        "website": "https://www.tend.io",
        "phone": "123-123-1234",
        "address": "2 N. LaSalle St.",
        "city": "Chicago",
        "state": "IL",
        "zip": "",
        "country": ""
    },
    "title": "Co-Founder",
    "bio": "Co-Founder: Tend [New] (http://tend.io ) Bitesize PR (http://BitesizePR.com ) // Source Sleuth (http://SourceSleuth.com ) // Lift (http://ThisIsLift.com )",
    "website": "https://www.tend.io",
    "address": "2 N. LaSalle St.",
    "city": "Chicago",
    "state": "IL",
    "zip": "",
    "country": "",
    "photo": "https://d2ojpxxtu63wzl.cloudfront.net/static/ae852ad1a29f3a06cc2af1fa4a3f9638_cef81b960bfeff853bddc25324d95107c7b6a5c7f9f77abbfbca394d0190102d",
    "facebook": "",
    "twitter": "https://twitter.com/ryanevans",
    "linkedin": "https://www.linkedin.com/profile/view?id=11981929",
    "a_customfield_id": "the custom field value",
    "activity": {
        "sessions": 32,
        "visits": 102
    },
    "pages": ["test.com","test.com/blog"],
    "entrypages": ["test.com","test.com/blog"],
    "segments": ["Customers","Hot Lead"],
    "events": ["Stripe Charge"],
    "referrers": ["Google","Facebook"],
    "params": {
        "campaignids": ["1234","5678"],
        "adgroupids": ["1234","5678"],
        "networks": ["foo","bar"],
        "creatives": ["foo","bar"],
        "keywords": ["foo","bar"],
        "utm_campaigns": ["foo","bar"],
        "utm_terms": ["foo","bar"],
        "utm_mediums": ["foo","bar"],
        "utm_sources": ["foo","bar"],
        "utm_contents": ["foo","bar"]
    },
},
...
"paginator": {
    "total_count":100,
    "total_pages":2,
    "current_page":1,
    "limit":50
}

Get contact

  • GET /contacts/{id} will return the specified contact.
curl -u user:pass https://tend.io/api/v1/contacts/123
{
    "id": 123,
    "ip": "123.12.12.123",
    "name": "Marty Thomas",
    "firstName": "Marty",
    "lastName": "Thomas",
    "email": "marty@tend.io",
    "company": {
        "id": 123,
        "name": "Tend",
        "website": "https://www.tend.io",
        "phone": "123-123-1234",
        "address": "2 N. LaSalle St.",
        "city": "Chicago",
        "state": "IL",
        "zip": "",
        "country": ""
    },
    "title": "Co-Founder"
    "bio": "Co-Founder at Tend. Founder & Developer at Purlem. Husband to my biggest cheerleader. And father to the new loves of my life.",
    "website": "https://www.tend.io",
    "address": "2 N. LaSalle St.",
    "city": "Chicago",
    "state": "IL",
    "zip": "",
    "country": "",
    "photo": "https://d2ojpxxtu63wzl.cloudfront.net/static/0cf998559aa4eae658ff31c0b338f155_344b70e63894af453574c5e548d38496ca282ca605c6225d10e2856518bf570c",
    "facebook": "",
    "twitter": "http://twitter.com/martyjthomas",
    "linkedin": "https://www.linkedin.com/in/martinjthomas",
    "a_customfield_id": "the custom field value",
    "activity": {
        "sessions": 1,
        "visits": 6
    },
    "pages": ["test.com","test.com/blog"],
    "entrypages": ["test.com","test.com/blog"],
    "segments": ["Customers","Hot Lead"],
    "events": ["Stripe Charge"],
    "referrers": ["Google","Facebook"],
    "params": {
        "campaignids": ["1234","5678"],
        "adgroupids": ["1234","5678"],
        "networks": ["foo","bar"],
        "creatives": ["foo","bar"],
        "keywords": ["foo","bar"],
        "utm_campaigns": ["foo","bar"],
        "utm_terms": ["foo","bar"],
        "utm_mediums": ["foo","bar"],
        "utm_sources": ["foo","bar"],
        "utm_contents": ["foo","bar"]
    },
}

Search contacts

  • GET /contacts/search?criteria[{field}]={value} will return the searched contact.
curl -u user:pass https://tend.io/api/v1/contacts/search?criteria[city]=Chicago&criteria[state]=IL

NOTE: Can also perform a search for part of the values using "%" (ie criteria[email]=%@domain.com)

{
    "id": 123,
    "ip": "123.12.12.123",
    "name": "Marty Thomas",
    "firstName": "Marty",
    "lastName": "Thomas",
    "email": "marty@tend.io",
    "company": {
        "id": 123,
        "name": "Tend",
        "website": "https://www.tend.io",
        "phone": "123-123-1234",
        "address": "2 N. LaSalle St.",
        "city": "Chicago",
        "state": "IL",
        "zip": "",
        "country": ""
    },
    "title": "Co-Founder"
    "bio": "Co-Founder at Tend. Founder & Developer at Purlem. Husband to my biggest cheerleader. And father to the new loves of my life.",
    "website": "https://www.tend.io",
    "address": "2 N. LaSalle St.",
    "city": "Chicago",
    "state": "IL",
    "zip": "",
    "country": "",
    "photo": "https://d2ojpxxtu63wzl.cloudfront.net/static/0cf998559aa4eae658ff31c0b338f155_344b70e63894af453574c5e548d38496ca282ca605c6225d10e2856518bf570c",
    "facebook": "",
    "twitter": "http://twitter.com/martyjthomas",
    "linkedin": "https://www.linkedin.com/in/martinjthomas",
    "a_customfield_id": "the custom field value",
    "activity": {
        "sessions": 1,
        "visits": 6
    },
    "pages": ["test.com","test.com/blog"],
    "entrypages": ["test.com","test.com/blog"],
    "segments": ["Customers","Hot Lead"],
    "events": ["Stripe Charge"],
    "referrers": ["Google","Facebook"],
    "params": {
        "campaignids": ["1234","5678"],
        "adgroupids": ["1234","5678"],
        "networks": ["foo","bar"],
        "creatives": ["foo","bar"],
        "keywords": ["foo","bar"],
        "utm_campaigns": ["foo","bar"],
        "utm_terms": ["foo","bar"],
        "utm_mediums": ["foo","bar"],
        "utm_sources": ["foo","bar"],
        "utm_contents": ["foo","bar"]
    },
}

Add contact

  • POST /contacts will add a new contact from the parameters passed.
curl -u user:pass -i -X POST -d 'email=joe@test.com&firstName=Joe&lastName=Test' https://tend.io/api/v1/contacts

NOTE: Pass the company_id to associate the contact with a particular company.

This will return 201 Success if the insert was a success along with the current JSON representation of the contact.

Update contact

  • PUT /contacts/{id} will update the project from the parameters passed.
curl -u user:pass -i -X PUT -d 'city=Boulder&state=CO' https://tend.io/api/v1/contacts/801

This will return 200 OK if the update was a success along with the current JSON representation of the contact.

Delete contact

  • DELETE /contacts/{id} will delete the contact.
curl -u user:pass -i -X DELETE https://tend.io/api/v1/contacts/123

This will return 200 Ok if successful.

Get contact visit history

  • GET /contacts/{id}/visits will return the visits for the specified contact.
curl -u user:pass https://tend.io/api/v1/contacts/123/visits
{
    "id": 1,
    "domain": "tend.io",
    "page": "/",
    "referrer": "google",
    "date": "2016-12-15T13:43:59-06:00"
},
{
    "id": 2,
    "domain": "tend.io",
    "page": "/pricing",
    "referrer": "",
    "date": "2016-12-15T13:43:59-06:00"
}
...
"paginator": {
    "total_count":100,
    "total_pages":2,
    "current_page":1,
    "limit":50
}

Get contact segments

  • GET /contacts/{id}/segments will return the segments associated with the specified contact.
curl -u user:pass https://tend.io/api/v1/contacts/123/segments
{
    "id": 235,
    "name": "Customer"
},
{
    "id": 235,
    "name": "Hot Lead"
}

Get contact events

  • GET /contacts/{id}/events will return the events associated with the specified contact.
curl -u user:pass https://tend.io/api/v1/contacts/123/events
{
    "id": 123,
    "name": "Stripe Charge"
},
{
    "id": 456,
    "name": "Viewed Checkout Page"
}

Companies

Get all companies

  • GET /companies will return all of the companies in the account.
curl -u user:pass https://tend.io/api/v1/companies
{
    "id": 123,
    "name": "Marty Thomas",
    "website": "https://www.tend.io",
    "phone": "123-123-1234",
    "address": "2 N. LaSalle St.",
    "city": "Chicago",
    "state": "IL",
    "zip": "",
    "country": ""
}
...
"paginator": {
    "total_count":100,
    "total_pages":2,
    "current_page":1,
    "limit":50
}

Get company

  • GET /contacts/{id | website} will return the specified company.
curl -u user:pass https://tend.io/api/v1/contacts/123
{
    "id": 123,
    "name": "Marty Thomas",
    "website": "https://www.tend.io",
    "phone": "123-123-1234",
    "address": "2 N. LaSalle St.",
    "city": "Chicago",
    "state": "IL",
    "zip": "",
    "country": ""
}

Search contacts

  • GET /companies/search?criteria[{field}]={value} will return the searched company.
curl -u user:pass https://tend.io/api/v1/contacts/search?criteria[city]=Chicago&criteria[state]=IL

NOTE: Can also perform a search for part of the values using "%" (ie criteria[phone]=123%)

{
    "id": 123,
    "name": "Marty Thomas",
    "website": "https://www.tend.io",
    "phone": "123-123-1234",
    "address": "2 N. LaSalle St.",
    "city": "Chicago",
    "state": "IL",
    "zip": "",
    "country": ""
}

Add company

  • POST /companies will add a new company from the parameters passed.
curl -u user:pass -i -X POST -d 'name=ABC Corp&website=abccorp.com' https://tend.io/api/v1/companies

This will return 201 Success if the insert was a success along with the current JSON representation of the company.

Update company

  • PUT /companies/{id | website} will update the project from the parameters passed.
curl -u user:pass -i -X PUT -d 'city=Boulder&state=CO' https://tend.io/api/v1/companies/123

This will return 200 OK if the update was a success along with the current JSON representation of the contact.

Delete company

  • DELETE /companies/{id} will delete the company.
curl -u user:pass -i -X DELETE https://tend.io/api/v1/companies/123

This will return 200 Ok if successful.

Get company contacts

  • GET /companies/{id | website}/contacts will return the contacts for the specified company.
curl -u user:pass https://tend.io/api/v1/companies/123/contacts
{
    "id": 123,
    "ip": "123.12.12.123",
    "name": "Marty Thomas",
    "firstName": "Marty",
    "lastName": "Thomas",
    "email": "marty@tend.io",
    "company": {
        "id": 123,
        "name": "Tend",
        "website": "https://www.tend.io",
        "phone": "123-123-1234",
        "address": "2 N. LaSalle St.",
        "city": "Chicago",
        "state": "IL",
        "zip": "",
        "country": ""
    },
    "title": "Co-Founder",
    "bio": "Co-Founder at Tend. Founder & Developer at Purlem. Husband to my biggest cheerleader. And father to the new loves of my life.",
    "website": "https://www.tend.io",
    "address": "2 N. LaSalle St.",
    "city": "Chicago",
    "state": "IL",
    "zip": "",
    "country": "",
    "photo": "https://d2ojpxxtu63wzl.cloudfront.net/static/0cf998559aa4eae658ff31c0b338f155_344b70e63894af453574c5e548d38496ca282ca605c6225d10e2856518bf570c",
    "facebook": "",
    "twitter": "http://twitter.com/martyjthomas",
    "linkedin": "https://www.linkedin.com/in/martinjthomas",
    "a_customfield_id": "the custom field value",
    "activity": {
        "sessions": 1,
        "visits": 6
    },
    "pages": ["test.com","test.com/blog"],
    "entrypages": ["test.com","test.com/blog"],
    "segments": ["Customers","Hot Lead"],
    "events": ["Stripe Charge"],
    "referrers": ["Google","Facebook"],
    "params": {
        "campaignids": ["1234","5678"],
        "adgroupids": ["1234","5678"],
        "networks": ["foo","bar"],
        "creatives": ["foo","bar"],
        "keywords": ["foo","bar"],
        "utm_campaigns": ["foo","bar"],
        "utm_terms": ["foo","bar"],
        "utm_mediums": ["foo","bar"],
        "utm_sources": ["foo","bar"],
        "utm_contents": ["foo","bar"]
    },
},
{
    "id": 456,
    "ip": "123.12.12.123",
    "name": "Ryan Evans",
    "firstName": "Ryan",
    "lastName": "Evans",
    "email": "ryan@tend.io",
    "company": {
        "id": 123,
        "name": "Tend",
        "website": "https://www.tend.io",
        "phone": "123-123-1234",
        "address": "2 N. LaSalle St.",
        "city": "Chicago",
        "state": "IL",
        "zip": "",
        "country": ""
    },
    "title": "Co-Founder",
    "bio": "Co-Founder: Tend [New] (http://tend.io ) Bitesize PR (http://BitesizePR.com ) // Source Sleuth (http://SourceSleuth.com ) // Lift (http://ThisIsLift.com )",
    "website": "https://www.tend.io",
    "address": "2 N. LaSalle St.",
    "city": "Chicago",
    "state": "IL",
    "zip": "",
    "country": "",
    "photo": "https://d2ojpxxtu63wzl.cloudfront.net/static/ae852ad1a29f3a06cc2af1fa4a3f9638_cef81b960bfeff853bddc25324d95107c7b6a5c7f9f77abbfbca394d0190102d",
    "facebook": "",
    "twitter": "https://twitter.com/ryanevans",
    "linkedin": "https://www.linkedin.com/profile/view?id=11981929",
    "a_customfield_id": "the custom field value",
    "activity": {
        "sessions": 32,
        "visits": 102
    },
    "pages": ["test.com","test.com/blog"],
    "entrypages": ["test.com","test.com/blog"],
    "segments": ["Customers","Hot Lead"],
    "events": ["Stripe Charge"],
    "referrers": ["Google","Facebook"],
    "params": {
        "campaignids": ["1234","5678"],
        "adgroupids": ["1234","5678"],
        "networks": ["foo","bar"],
        "creatives": ["foo","bar"],
        "keywords": ["foo","bar"],
        "utm_campaigns": ["foo","bar"],
        "utm_terms": ["foo","bar"],
        "utm_mediums": ["foo","bar"],
        "utm_sources": ["foo","bar"],
        "utm_contents": ["foo","bar"]
    },
},
...
"paginator": {
    "total_count":100,
    "total_pages":2,
    "current_page":1,
    "limit":50
}

Visits

Get visits

  • GET /visits/{id} will return the visit data
curl -u user:pass https://tend.io/api/v1/visits/123
{
    "id": 1234,
    "domain": "tend.io",
    "page": "/",
    "referrer": "google",
    "date": "2016-12-15T13:43:59-06:00"
}

Get all visits

  • GET /visits will return the full visit history.

To and From Dates (optional)

  • GET /visits?from={YYYY-MM-DD}&to={YYYY-MM-DD} will return visits between to and from dates provided.
curl -u user:pass https://tend.io/api/v1/visits
{
    "id": 1234,
    "domain": "tend.io",
    "page": "/",
    "referrer": "google",
    "date": "2016-12-15T13:43:59-06:00"
},
{
    "id": "TFf7rFIVGTaSTr8Gd4GRtH6zVFCBEfVoWuFxGBhk",
    "domain": "tend.io",
    "page": "/pricing",
    "referrer": "",
    "date": "2016-12-15T13:43:59-06:00"
}
...
"paginator": {
    "total_count":100,
    "total_pages":2,
    "current_page":1,
    "limit":50
    }

If the visit is associated it a contact, the contact's ID will be passed as the id integer. Otherwise, the visitor's anonymous ID will be provided.

Get all pages

  • GET /pages will return all pages visited and their count.
curl -u user:pass https://tend.io/api/v1/pages
{
    "page": "/",
    "visits": 9491
},
{
    "page": "/pricing",
    "visits": 2880
},
{
    "page": "/features",
    "visits": 2190
}
...
"paginator": {
    "total_count":100,
    "total_pages":2,
    "current_page":1,
    "limit":50
    }

Referrers

Get all referrers

  • GET /referrers will return all of the referrers in the account.
curl -u user:pass https://tend.io/api/v1/referrers
{
    "name": "direct"
},
{
    "name": "google"
},
{
    "name": "feedburner"
}
...
"paginator": {
    "total_count":100,
    "total_pages":2,
    "current_page":1,
    "limit":50
}

Get all referrer contacts

  • GET /referrers/{name}/contacts will return all of the contacts associated with a referrer.
curl -u user:pass https://tend.io/api/v1/referrers/google/contacts

This will return 200 OK if the contacts are found, along with the JSON representation of the associated contacts.

Get all referrer visits

  • GET /referrers/{name}/visits will return all of the visits associated with a referrer.
curl -u user:pass https://tend.io/api/v1/referrers/google/visits

This will return 200 OK if the contacts are found, along with the JSON representation of the associated visits.

Segments

Get all segments

  • GET /segments will return all of the segments in the account.
curl -u user:pass https://tend.io/api/v1/segments
{
    "id": 1,
    "name": "Customer"
},
{
    "id": 2,
    "name": "ViewedPricingPage"
}

Get segment

  • GET /segments/{id} will return the selected referrer.
curl -u user:pass https://tend.io/api/v1/segments/1
{
    "id": 1,
    "name": "Customer"
}

Add segment

  • POST /segments will add the segment from the parameters passed.
curl -u user:pass -i -X POST -d 'name=API' https://tend.io/api/v1/segments

This will return 201 Success if the insert was a success along with the current JSON representation of the segment.

Update segment

  • PUT /segments/{id} will update the segment from the parameters passed.
curl -u user:pass -i -X PUT -d 'name=API2' https://tend.io/api/v1/segments/123

This will return 200 Ok if the update was a success along with the current JSON representation of the segment.

Delete segment

  • DELETE /segments/{id} will delete the segment.
curl -u user:pass -i -X DELETE https://tend.io/api/v1/segments/123

This will return 200 Ok if successful.

Events

Get all events

  • GET /events will return all of the events in the account.
curl -u user:pass https://tend.io/api/v1/events
{
    "id": 1,
    "name": "Customer"
},
{
    "id": 2,
    "name": "ViewedPricingPage"
}

Get event

  • GET /events/{id} will return the selected event.
curl -u user:pass https://tend.io/api/v1/events/1
{
    "id": 1,
    "name": "Stripe Charge"
}

Add event

  • POST /events will add the event from the parameters passed.
curl -u user:pass -i -X POST -d 'name=API' https://tend.io/api/v1/events

This will return 201 Success if the insert was a success along with the current JSON representation of the event.

You can also assign a property to an event by using a colon (:) to separate the event name from the property value. (ie: Stripe Charge:$40)

Update event

  • PUT /events/{id} will update the event from the parameters passed.
curl -u user:pass -i -X PUT -d 'name=event_name' https://tend.io/api/v1/events/123

This will return 200 Ok if the update was a success along with the current JSON representation of the event.

Delete event

  • DELETE /event/{id} will delete the event.
curl -u user:pass -i -X DELETE https://tend.io/api/v1/events/123

This will return 200 Ok if successful.

Assign a Contact to a Event

  • POST /events/assign will assign the event from the parameters passed.

Will need to POST the contact's email, along with the event name.

curl -u user:pass -i -X POST -d 'email=user@domain&event=Stripe_Charge' https://tend.io/api/v1/events/assign
{
    "message": "events assigned to user@domain.com"
}