Organized around REST, using JSON for serialization and HTTP Basic Auth for 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.
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.
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.
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.
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 /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"]
},
}
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"]
},
}
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.
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 /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 /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 /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 /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"
}
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 /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": ""
}
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": ""
}
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.
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 /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 /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
}
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",
"device": "MacBook",
"ip": "127.0.0.1",
"params": {
"campaignid": ["1234","5678"],
"adgroupid": ["1234","5678"],
"network": ["foo","bar"],
"creative": ["foo","bar"],
"keyword": ["foo","bar"],
"utm_campaign": ["foo","bar"],
"utm_term": ["foo","bar"],
"utm_medium": ["foo","bar"],
"utm_source": ["foo","bar"],
"utm_content": ["foo","bar"]
},
"date": "2016-12-15T13:43:59-06:00"
}
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 betweento
andfrom
dates provided.
curl -u user:pass https://tend.io/api/v1/visits
{
"id": 1234,
"domain": "tend.io",
"page": "/",
"referrer": "google",
"device": "MacBook",
"ip": "127.0.0.1",
"params": {
"campaignid": ["1234","5678"],
"adgroupid": ["1234","5678"],
"network": ["foo","bar"],
"creative": ["foo","bar"],
"keyword": ["foo","bar"],
"utm_campaign": ["foo","bar"],
"utm_term": ["foo","bar"],
"utm_medium": ["foo","bar"],
"utm_source": ["foo","bar"],
"utm_content": ["foo","bar"]
},
"date": "2016-12-15T13:43:59-06:00"
},
{
"id": "TFf7rFIVGTaSTr8Gd4GRtH6zVFCBEfVoWuFxGBhk",
"domain": "tend.io",
"page": "/pricing",
"referrer": "",
"device": "MacBook",
"ip": "127.0.0.1",
"params": {
"campaignid": ["1234","5678"],
"adgroupid": ["1234","5678"],
"network": ["foo","bar"],
"creative": ["foo","bar"],
"keyword": ["foo","bar"],
"utm_campaign": ["foo","bar"],
"utm_term": ["foo","bar"],
"utm_medium": ["foo","bar"],
"utm_source": ["foo","bar"],
"utm_content": ["foo","bar"]
},
"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 /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
}
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 /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 /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.
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 /segments/{id}
will return the selected referrer.
curl -u user:pass https://tend.io/api/v1/segments/1
{
"id": 1,
"name": "Customer"
}
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.
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 /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.
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 /events/{id}
will return the selected event.
curl -u user:pass https://tend.io/api/v1/events/1
{
"id": 1,
"name": "Stripe Charge"
}
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
)
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/{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.
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"
}