The French version of this article has been updated since it was translated. Read the French version
Connect your tool through the API
Your software is not in the list? Generate an import token and have your own tool send your properties, bookings and jobs, with the custom source.
The video for this guide is coming soon.
The custom source (API) feeds The Big One from any tool: your in-house software, an automated spreadsheet, a tool we do not know. Your tool sends properties, bookings, jobs and schedule names with a simple request. This article shows you what to prepare and what to pass on to the person who will set up the connection. Allow 5 minutes on your side.
Your software is on the Integrations page? Link it without any development instead: Connect your management software.
What the connection syncs
| Data | Direction | Note |
|---|---|---|
| Properties | From your tool to The Big One | A property missing from a submission is never deleted |
| Bookings | From your tool to The Big One | Cancelled only if your tool declares a complete period |
| Jobs | From your tool to The Big One | A job that is started, completed or approved is never overwritten |
| Schedule names | From your tool to The Big One | Matched with existing accounts; no account is created |
Before you start
- You are an administrator: the Integrations page is for the administrator only.
- Someone knows how to write a small program that sends data: your developer, or the vendor of your tool.
- Each property, booking and job in your tool has an identifier that does not change. It is used to avoid creating any duplicate.
Generate the import token
Step by step
- 1
Open Settings › Workflows & integrations › Integrations.
- 2
At the top of the page, click the “Developers” filter. The “Custom source (API)” card is there.
- 3
Click Generate a token. The “Your import token” window opens.
- 4
Click Copy token. The message “Token copied.” appears.
- 5
Store the token in a safe place, then close the window. The card carries the label “Active token”.
Pass the information on to your developer
Step by step
- 1
On the card, next to “Endpoint URL:”, click Copy. The message “URL copied.” appears.
- 2
Click View the documentation. The page describes the address, the headers, a complete example, the import rules and the limits.
- 3
Send your developer the endpoint URL, the link to the documentation and, through a safe channel, the token.
The rules to know before writing the program:
| Rule | What it means |
|---|---|
| One identifier per item | Each item is recognised by its identifier: sending the same content again creates no duplicate |
| Property missing from a submission | It is never deleted: only the “active” value sent counts |
| Linen of the property | With each submission, the linen part of the sheet is replaced entirely: an entry made by hand is overwritten |
| Job already started | It is never overwritten: only its empty fields are filled in |
Check the imports
Step by step
- 1
On the “Custom source (API)” card, read the “Last import:” line. It gives the date of the last submission received.
- 2
Expand “Last 30 imports”. Each line counts, by type of data, the items created, updated and kept.
- 3
A line reports errors? Expand it to read the details, then pass them on to your developer.
Revoke the token
Do this if the token has been passed around, or when you change tool.
Step by step
- 1
On the card, click Revoke. The “Revoke the token?” window opens.
- 2
Click Revoke token. The message “Token revoked: future calls will be rejected.” appears.
- 3
To reconnect your tool, click Generate a token again and give the new token to your developer.
Frequently asked questions
Is a developer needed?
Yes. The custom source expects data sent by a program. Without a developer, link software from the Integrations page or an iCal link.
Can a property imported through the API be linked to a listing from another integration?
No. Your tool finds it by its identifier with each submission: it cannot be linked to a listing from another integration.
Can my tool be notified when a job is finished?
Yes. Under the “Developers” filter, the “Developer access” card lets you add an address to notify when a job is assigned, started, completed or approved.
What happens if I generate a new token?
The old one is revoked: submissions that use it are rejected. Give the new token to your developer.
Are cleaners' accounts created by the import?
No. No account is created by an import: names with no match are sent back to your tool so that you can invite the person.