Getting Started

Last Updated:

Your first step is to sign up for a Fortellis user account as a registered developer. This requires you to pay an annual fee and agree to the Fortellis Developer Terms and Conditions. You get a user account with access to all of the Developer Network features - everything you need to publish your APIs and solutions on Fortellis. Below are the steps to get started:

  1. Sign up as Fortellis user.
  2. Enter your name, your email (which will be your Fortellis user ID), and a password. 
  3. Select a security question and enter your answer.
  4. Enroll as an individual or a company/organization.
  5. Select the country you're in.
  6. Check the box to subscribe to Fortellis email updates (optional). 
  7. Read and check the box to accept the Developer Terms (required). 
  8. Click PROCEED to acknowledge that you will be billed for the Fortellis annual access fee.
  9. Check your inbox for your confirmation email.
  10. Next, you'll receive an invoice in your email for your developer access fee. Pay the fee for your first year of membership.  
  11. Your new Developer Account will be reviewed for approval. We'll email you when it's approved. 

The first time you login, take a moment to look at your account pages. These give you quick access to the items you publish or subscribe to on Fortellis.

  1. Click LOG IN in the Fortellis header.
  2. Enter your email address and password.
  3. Click the LOG IN button.
  4. The button in the Fortellis header now displays your name. Click on your name to see your available account pages.
  5. The Developer Account page lists your registered software solutions.
  6. Click on any of the list items to see details, check status, or edit information.  

Authorization Flows

We use the OAuth 2.0 authentication protocol relied on by industry leaders such as Google and Facebook. Authentication is done with your Fortellis API Key. Authorizations are processed by tokens which expire. For example, the expires_in value of 3600 (seconds) expires one hour from the time of response. Tokens can be re-used until expiration. Expired tokens return the HTTP 401 Unauthorized status code. Below are details for each OAuth method:

Making Requests

Refer to the individual API Spec page for each endpoint (method) for instructions on making requests. 

Sample Requests

The following examples use a fictional server address: https://api.example.com.

Cancel Appointment

curl -v -X POST https://api.example.com/v1/appointments/I-1TJ3GAGG82Y9/cancel \
  --H "Content-Type:application/json" \
  --H "Authorization: Bearer <Access-Token>” \
  --d '{
        "note": "Canceling the appointment.”
        }'

Invoicing

The following Invoicing API example call returns details for four invoices beginning with the third invoice. It includes the total count of invoices in the response.

curl -v -X GET https://api.example.com/v1/invoicing/invoices?page=3&page_size=4&total_count_required=true 
  -H "Content-Type:application/json" \
  -H "Authorization: Bearer <Access-Token>” \

HTTP Methods

Below are the general Fortellis methods and descriptions.

Method Description
GET Requests data from a resource.
POST Submits data to a resource.
PUT Updates a resource.
PATCH Partially updates a resource.
DELETE Deletes a resource.
REDIRECT Specifies the target URL is a redirect to the Fortellis account.
 

Query Parameters

Below are common parameters, their types and descriptions. 

Parameter Type Description
count Integer The number of items in the response.
end_time Integer The end date and time of the response. Format: end_time=2016-03-06T11:00:00Z.
page Integer The zero-relative start index of the entire list of items returned in the response. The combination of page=0 and page_size=20 returns the first 20 items. The combination of page=20 and page_size=20 returns the next 20 items.
page_size Integer The number of items to return in the response.
sort_order String Sorts the appointments in the response by value such as the create time or update time.
start_time String The start date and time of the response. Format: end_time=2016-03-06T11:00:00Z.
 

HTTP Status Codes

Below are response status codes and descriptions.

Status Code Description
200 OK The request succeeded.
201 Created A POST method successfully created a resource
202 Accepted The server accepted the request and will execute it.
204 No Content The server successfully executed the method but returns no response body.
400 Bad Request INVALID_REQUEST. Request is not well-formed, syntactically incorrect or violates the schema.
401 Unauthorized AUTHENTICATION_FAILURE. Authentication failed due to invalid authentication credentials.
403 Forbidden OT_AUTHORIZED. Authorization failed due to insufficient permissions.
404 Not Found RESOURCE_NOT_FOUND. The specified resource does not exist.
405 Method Not Allowed METHOD_NOT_SUPPORTED. The server does not implement the requested HTTP method.
406 Not Acceptable MEDIA_TYPE_NOT_ACCEPTABLE. The server does not implement the media type that would be acceptable to the client.
 

What's Next?

Develop and Market a Solution - design and market your solution to users.