Welcome to Daniel Timothy Leads API Documentation. Our API is custom designed to help automate manual processes done throughout Daniel Timothy Leads. This API is built using Microsoft's Web API 2, using OAuth 2.0 to authenticate all requests.
Our API supports all CRUD functions on most resources except for particular resources that must be created and updated manually. Giving you the ability to easily add Companies, Prospects, create the Campaigns and start sending out emails automatically. From there you can pull data to collect statistics and manage your resources.
The Getting started section will go over authenticating and making requests while covering error handling. From there the API resources section will cover all the specific endpoints for each resource and the variables exposed to perform actions.
Our API is still in development stages. If you have any additional questions, feedback or bug reports please contact [email protected] This being our first released version, we are open to ideas and suggestions on what actions the resources should to perform, if missing.
Getting Started
Authentication
Authentication is knowing the identity of the user. For example, Alice logs in with her username and password, and the server uses the password to authenticate Alice.
Daniel Timothy Leads API uses OAuth 2.0 to authenticate request
- The user enters a name and password into the client.
- The client sends these credentials to the authorization server.
- The authorization server authenticates the credentials and returns an access token.
- To access a protected resource, the client includes the access token in the Authorization header of the HTTP request.
You can only request an access token once every 60 seconds and only 30 times per hour. Doing more frequently with trigger rate limiting, please ensure you are saving the tokens and making a request for a new access token when it is about to expire.
URL
https://danieltimothyleads.com/oauth/token
Request Parameters
| Parameter | Value | Description |
|---|---|---|
| grant_type | password | The method used to get the access token. In this case the password is used. |
| username | your account username | The username associated with your account. Daniel Timothy Leads uses your email as your Username. |
| password | your account password | The password associated to the account |
Request
import requests
# create parameters
parms = {
'grant_type': 'password',
'username': '<username>',
'password': '<password>'
}
## make the requst and check the response code
response = requests.post("https://danieltimothyleads.com/oauth/token", data = parms)
print(response)
## get data from response
data = response.json()
print(data)
Response
{
"access_token": "<access_token>",
"token_type": "bearer",
"expires_in": "7199",
"refresh_token": "<refresh_token>",
"username": "<username>",
"user_id": "<user_id>",
".issued": "<issued datetime>",
".expires": "<expires datetime>"
}
Response Parameters
| Parameter | Description |
|---|---|
| access_token | Security credentials for a login session and identifies the user. (2 Hour Lifetime) |
| token_type | Defines that the access token is to be generated and returned back. Will always be type "bearer" |
| expires_in | Time in seconds from the date issues to when the access token will expire. |
| refresh_token | Token used to generate a new access token. (14 Day Lifetime) |
| username | The Username associated with the access credentials. Daniel Timothy leads currently uses your email as your Username. |
| user_id | The unique id to identify the user associated with the access credentials. |
| .issued | UTC Date and time issued |
| .expires | UTC Date and time expires |
The access token is then used in every HTTP Header to authorize each request. After 7199 seconds (2 hours) the access token will expire and will need to be refreshed. This is done by using the refresh token to request a new set of tokens.
Refresh The Access Token
import requests
parms = {
'grant_type': 'refresh_token',
'refresh_token': '<refresh_token>',
}
response = requests.post("https://danieltimothyleads.com/oauth/token", data = parms)
print(response)
data = response.json()
print(data)
When the access token is refreshed, you are returned a new access token along with a new refresh token. The old refresh token will expire right away so store the new refresh token to use for the next refresh.
Authorization
Authorization is deciding whether a user is allowed to perform an action. For example, Alice has permission to get a resource but not create a resource.
Daniel Timothy Leads uses user roles to authorize a particular resource. As of right now there are no defining scopes to declare what specific resources a user can have access to. But based on the defined user roles, owner and manager can view and make changes to any resource no matter who owns the resource. While the user role can only affect a resource if they own it.
Include Access Token in HTTP Header
import requests
headers = { "Authorization": "Bearer " + '<access_token>' }
response = requests.get("https://danieltimothyleads.com/api/account", headers=headers)
data = response.json()
print(data)
Response Codes
HTTP Status Codes
| Code | Description |
|---|---|
| 200 OK | Request was successful |
| 201 Created | Resource successfully Created |
| 204 No Content | Request was successful but not content is returned |
| 400 Bad Request | Bad input. The URL or parameters may be incorrect. |
| 401 Unauthorized | Not authorized to access the resource. |
| 404 Not Found | Resource Not Found |
| 429 Too Many Requests | Rate limiting to many request |
| 500 Internal Server Error | Server is not processing correctly. Request is most likely valid but needs to be tried later |
| 503 Service Unavailable | Service is Unavailable. Daniel Timothy Leads may be updating. |
Rate Limiting
Daniel Timothy Leads rate limits requests made to the API based on per user request. As of right now it is set to 100 requests per minute. Please ensure you are not are not going over this request limit. If the rate limit is exceeded, you will receive a HTTP response with a status code of 429.
Requesting an access token is limited to 1 request per minute and 30 requests per hour. It is important to save the access token and only request a new one when it is about to expire. If the rate limit is exceeded, all requestS to the authorization endpoint from that IP address will receive a HTTP response with a status code of 429.
API Resources
Account
The account associated with the user login.
Parameters
| Parameter | Description | Access |
|---|---|---|
| accountId | Unique Id to reference your account | ReadOnly |
| companyName | Your Accounts Company Name | |
| accountEmail | Main email for your account | Read Only |
| emailConfirmed | Is main email confirmed or not | Read Only |
| phoneNumber | Main phone number for your account | |
| activeSubscription | Is there a active subscription | Read Only |
| dateRegistered | The UTC date the account was registered | Read Only |
| dateActivated | The UTC date the account activated a subscription | Read Only |
GET
https://danieltimothyleads.com/api/account
PATCH
https://danieltimothyleads.com/api/account
Campaign
Schedule prospects with an email template to automatically send out emails and wait for a response.
Parameters
| Parameter | Description | Access |
|---|---|---|
| campaignId | Unique Id to identify the campaign | Read Only |
| status | The current status of the campaign (Off, Active) | Read Only |
| scheduledMailLimit | Number of emails allowed to be scheduled at once | |
| onReplyAction | Action to perform after a reply message has been received. (PAUSE, NEXT, CONTINUE) | |
| templateId | The template the campaign references when sending emails | |
| companyId | The unique company Id that the campaign belongs to | Read Only |
GET
https://danieltimothyleads.com/api/campaigns
GET
https://danieltimothyleads.com/api/campaigns/{campaignId}
POST
https://danieltimothyleads.com/api/campaigns
PATCH
https://danieltimothyleads.com/api/campaigns/{campaignId}
PATCH - TURN ON
https://danieltimothyleads.com/api/campaigns/{campaignId}/turnon
PATCH - TURN OFF
https://danieltimothyleads.com/api/campaigns/{campaignId}/turnoff
DELETE
https://danieltimothyleads.com/api/campaigns/{campaignId}
Campaign Sequence
A prospect that belongs to a campaign sequenced to send out mail.
Parameters
| Parameter | Description | Access |
|---|---|---|
| campaignId | CampaignId the sequence is associated with | Read Only |
| prospectId | ProspectId the sequence is associated with | Read Only |
| status | The Status of the prospect in the sequence (Active, Replied, Paused, Pending) | Read Only |
| stage | The current stage of the email (New Thread, Follow Up) | Read Only |
| indexOrder | The prospects index order to determine when to schedule the email | |
| sendTime | The time for when the email is scheduled (UTC) | Read Only |
GET
https://danieltimothyleads.com/api/sequences
GET
https://danieltimothyleads.com/api/sequences/{campaignId}?prospectId={prospectId}
POST
https://danieltimothyleads.com/api/sequences
PATCH
https://danieltimothyleads.com/api/sequences/{campaignId}?prospectId={prospectId}
DELETE
https://danieltimothyleads.com/api/sequences/{campaignId}?prospectId={prospectId}
Company
Hold relative information about a company including prospects, logs, campaigns and messages.
Parameters
| Parameter | Description | Access |
|---|---|---|
| companyId | Unique Id to identify the company | ReadOnly |
| companyName | The name of the company | |
| website | The website associated with the company | |
| industry | The relative industry the company belongs to | |
| location | The location of the company | |
| userId | The Id of the user the owns the company |
GET
https://danieltimothyleads.com/api/companies
GET
https://danieltimothyleads.com/api/companies/{companyId}
POST
https://danieltimothyleads.com/api/companies
PATCH
https://danieltimothyleads.com/api/companies/{companyId}
DELETE
https://danieltimothyleads.com/api/companies/{companyId}
Company Log
Log relative information about a company.
Parameters
| Parameter | Description | Access |
|---|---|---|
| logId | Unique Id to identify the company log | ReadOnly |
| type | The type of log message | |
| message | The message contents of the log | |
| dateCreated | The date the log was created (UTC) | Read Only |
| companyId | The id of the company the log belongs to |
GET
https://danieltimothyleads.com/api/companylogs
GET
https://danieltimothyleads.com/api/companylogs/{logId}
POST
https://danieltimothyleads.com/api/companylogs
PATCH
https://danieltimothyleads.com/api/companylogs/{logId}
DELETE
https://danieltimothyleads.com/api/companylogs/{logId}
Messages
Sent Messages
Parameters
| Parameter | Description | Access |
|---|---|---|
| sentMessageId | The unique Id to identify the sent message | Read Only |
| fromEmail | The email of who sent the message | Read Only |
| toEmail | The email the message was sent to | Read Only |
| toName | The name of the prospect the message was sent to | Read Only |
| subjectLine | The subject line of the message | Read Only |
| htmlBody | The message body contents in HTML | Read Only |
| timeDelivered | The time the message was sent | Read Only |
| prospectId | The id of the prospect the message belongs to | Read Only |
GET
https://danieltimothyleads.com/api/Messages/Sent
GET
https://danieltimothyleads.com/api/Messages/Sent/{sentMessageId}
Received Messages
Parameters
| Parameter | Description | Access |
|---|---|---|
| replyMessageId | The unique id to identify the reply message | Read Only |
| fromName | The name of who sent the message | Read Only |
| fromEmail | The email of who sent the message | Read Only |
| toEmail | The email the message was delivered to | Read Only |
| subjectLine | The subject line of the message | Read Only |
| htmlBody | The body contents of the message in HTML | Read Only |
| timeReceived | The time the message was received | Read Only |
| prospectId | The id of the prospect the message belongs to | Read Only |
| sentMessageId | The id of the sent message that this reply belongs to | Read Only |
GET
https://danieltimothyleads.com/api/Messages/Replies
GET
https://danieltimothyleads.com/api/Messages/Replies/{replyMessageId}
Scheduled Messages
Parameters
| Parameter | Description | Access |
|---|---|---|
| prospectId | The id of the prospect the message belongs to | Read Only |
| campaignId | The id of the campaign the message belongs to | Read Only |
| firstName | The first name of the prospect | Read Only |
| lastName | The last name of the prospect | Read Only |
| The prospects email | Read Only | |
| title | The business title of the prospect | Read Only |
| scheduleTime | The time the email is scheduled to send. (UTC) | |
| replyIndex | The current reply index of the template replies to send out | Read Only |
GET
https://danieltimothyleads.com/api/Messages/scheduled
GET
https://danieltimothyleads.com/api/Messages/scheduled/{campaignId}?prospectId={ProspectId}
Patch
https://danieltimothyleads.com/api/Messages/scheduled/{campaignId}?prospectId={ProspectId}
Prospect
A prospect that belongs to a company used to send mail.
Parameters
| Parameter | Description | Access |
|---|---|---|
| prospectId | Unique id to identify the prospect | Read Only |
| firstName | The first name of the prospect | |
| lastName | The last name of the prospect | |
| title | The business title of the prospect | |
| The prospect email address | ||
| companyId | The company id the prospect belongs to |
GET
https://danieltimothyleads.com/api/prospects
GET
https://danieltimothyleads.com/api/prospects/{prospectId}
POST
https://danieltimothyleads.com/api/prospects
PATCH
https://danieltimothyleads.com/api/prospects/{prospectId}
DELETE
https://danieltimothyleads.com/api/prospects/{prospectId}
Reply Template
A mail template to reply to an original email thread.
Parameters
| Parameter | Description | Access |
|---|---|---|
| replyTemplateId | Unique id to identify the reply template | Read Only |
| name | The name of the reply template | |
| htmlBody | The body contents of the reply template in HTML | |
| userId | The id of the user of who created the reply template | Read Only |
GET
https://danieltimothyleads.com/api/replytemplates
GET
https://danieltimothyleads.com/api/replytemplates/{replyTemplateId}
POST
https://danieltimothyleads.com/api/replytemplates
PATCH
https://danieltimothyleads.com/api/replytemplates/{replyTemplateId}
DELETE
https://danieltimothyleads.com/api/replytemplates/{replyTemplateId}
Subscription
The subscription attached to the account.
Parameters
| Parameter | Description | Access |
|---|---|---|
| planName | The plan name of the subscription active on the account | Read Only |
| userAccountLimit | The number of user allowed | Read Only |
| emailAccountLimit | The number of email accounts allowed | Read Only |
| dailySendLimit | The number of emails sent per day allowed | Read Only |
| prospectLookupLimit | The number of email lookups per month allowed | Read Only |
GET
https://danieltimothyleads.com/api/subscription
Template
Mail template used to schedule prospect messages and create a new email thread.
Parameters
| Parameter | Description | Access |
|---|---|---|
| templateId | Unique id to identify the template | Read Only |
| name | The name of the template | |
| subject | The email subject line | |
| htmlBody | The body contents of the email in HTML | |
| templateSettingId | The id of the template settings the template references | |
| unsubscribeAvailable | Is the option to unsubscribe included in the HTML body | |
| userId | The id of the user who created the template | Read Only |
GET
https://danieltimothyleads.com/api/templates
GET
https://danieltimothyleads.com/api/templates/{templateId}
POST
https://danieltimothyleads.com/api/templates
PATCH
https://danieltimothyleads.com/api/templates/{templateId}
DELETE
https://danieltimothyleads.com/api/templates/{templateId}
POST - ADD REPLY
https://danieltimothyleads.com/api/templates/{templateId}/addreply
DELETE - REMOVE REPLY
https://danieltimothyleads.com/api/templates/{templateId}/removereply?replyTemplateId={replyTemplateId}
Template Settings
Settings the templates use when scheduling messages.
Parameters
| Parameter | Description | Access |
|---|---|---|
| templateSettingId | Unique id to identify the template setting | Read Only |
| name | The name of the setting | |
| scheduleTime | The default schedule time of the emails | |
| restrictionId | The id of the setting restrictions the settings references |
GET
https://danieltimothyleads.com/api/templatesettings
GET
https://danieltimothyleads.com/api/templatesettings/{templateSettingId}
POST
https://danieltimothyleads.com/api/templatesettings
PATCH
https://danieltimothyleads.com/api/templatesettings/{templateSettingId}
DELETE
https://danieltimothyleads.com/api/templatesettings/{templateSettingId}
Template Setting Restrictions
Template Setting time restrictions to restrict the available time to send mail.
Parameters
| Parameter | Description | Access |
|---|---|---|
| restrictionId | Unique id to identify the restrictions | Read Only |
| restrictionName | The name of the restrictions | |
| monday | start and stop time restrictions for monday | |
| tuesday | start and stop time restrictions for tuesday | |
| wednesday | start and stop time restrictions for wednesday | |
| thursday | start and stop time restrictions for thursday | |
| friday | start and stop time restrictions for friday | |
| saturday | start and stop time restrictions for saturday | |
| sunday | start and stop time restrictions for sunday |
GET
https://danieltimothyleads.com/api/settingrestrictions
GET
https://danieltimothyleads.com/api/settingrestrictions/{restrictionId}
POST
https://danieltimothyleads.com/api/settingrestrictions
PATCH
https://danieltimothyleads.com/api/settingrestrictions/{restrictionId}
DELETE
https://danieltimothyleads.com/api/settingrestrictions/{restrictionId}
User
The user connected to an account
Parameters
| Parameter | Description | Access |
|---|---|---|
| userId | Unique id to identify the user | Read Only |
| firstName | The first name of the user | |
| lastName | The last name of the user | |
| The main email of the user account | Read Only | |
| emailConfirmed | Is the email confirmed | Read Only |
| phoneNumber | The phone number of the user account | Read Only |
GET
https://danieltimothyleads.com/api/users
GET
https://danieltimothyleads.com/api/users/{userId}
Patch
https://danieltimothyleads.com/api/users/{userId}