Talk to CoachAccountable programmatically using its API.
With the right developer resources you'll be able to build custom workflows, post data to or import data from other applictions, and generate spiffy reports by pulling data in realtime to cook up whatever is useful.
The menu on the left will get you around documentation of all of the functionality offered by the CoachAccountable API. Note towards the top the little check box labeled "Show Team functions". If you're working on a Team Edition account you'll want that checked, and otherwise can uncheck it to pare down the documentation to only what pertains to Basic accounts.
When you're looking at a given function, you'll find a little try now... button. Click it to reveal a live HTML form setup to make real calls of that function to the live API.
If you're logged into your account currently as you browse and interact with this documentation, you'll find that in many places where sensible to do so, parameter values will be either filled in for you (like your API credentials) or come with autosuggest options making it easy to fill in (like a listing of your clients and their respective IDs for ClientID inputs). This will help you to craft API calls that work and relate to your specific account more easily.
Be careful! These are real calls upon your account using the API, so don't make any calls you might regret (like deleting a client, yikes!).
Have fun, and if you have any questions or (especially) have a need that the API isn't currently capable of, drop me an email, john at.
Cheers!
All function calls are made by POSTing the called-for name-value pairs to the API endpoint URL, https://www.coachaccountable.com/API/
.
Assuming the connection is successful (HTTP 200) you can expect to get a JSON object back which ALWAYS contains the following 5 fields:
{ "status": "success", "result": "added", "return": { "ClientID": 413 }, "error": 0, "message": "The Client is added", "timezone": "America\/Los_Angeles" }
Here's what to expect with these 5 fields:
status
Will always be either success
or failure
. This is sort of a low-res alias for
error
, in that a value of success
guarantees that error
is 0
,
and a value of failure
guarantees that error
is some number greater than 0
.
result
This is a succinct symbol describing what happened with the call, and can be useful in differentiating result cases for certain API calls.
Here are the values that can be returned for result
:
added
- the item you were looking to add was indeed addedduplicateSkipped
- the item you were looking to add was detected as duplicate, and so returned the ID of the existing item insteadduplicateAdded
- the item you were looking to add was detected as duplicate, and a new one was added anywayupdated
- the item you were looking to update was indeed updatednoop
- i.e. "no op", the change you were looking to make had no effect (e.g. deactivating a client who's already deactivated)deleted
- the item you were looking to delete was indeed deletedloaded
- the item or items you were fetching by "get" call were returned as you would expectempty
- the item or items you were fetching turned out to be an empty set (e.g. fetching Actions for a client who has none)sent
- the message or notification you were looking to send was indeed sentreturn
This is an array of the value or values returned by the call.
For "add" functions this is most often a single name-value pair, like { "ClientID": 7 }
for a successful call to Client.add
.
Some functions have more than one return value, like Action.add, which indicates not only the ID of the newly added Action but
also the ID of the ActionProject to which it was added: { "ActionID": 22, "ActionProjectID": 3 }
.
For "get" functions this is always an array of zero or more elements who are themselves associative arrays.
error
This is always an integer value of which error if any occurred with the API call. When there was no error,
error
always has the value of numeric zero (0
).
message
This is a generally human friendly message about what happened with the call, whether successful or in error. They are useful for logging purposes, certainly for error cases and perhaps even for successful ones.
The messages you can get are NOT one-to-one with error codes, as in for the same error code you can get different error messages
(so do string matching on message
for your error handling logic at your own risk!).
You might've noticed in the above there's a sixth field in the JSON object, timezone
. Let's talk about that.
timezone
timezone
ONLY appears in successful API call results. timezone
is simply an echoing out
of the timezone that has been set as the "preferred" one for intereactions in the API. Including this is
for the benefit of those calls which return date/time values (e.g. the times of Appointments scheduled for a given client),
to make it unambiguously clear in which timezone those times are in.
In general you should be able to presume you know which timezone you have set for your API account settings, but
in case you've got other people potentially mucking around with the configuration, the inclusion of timezone
enables
you to always correctly interpret times you get back from the API.
CoachID
, intM | Male |
F | Female |
U | Unspecified // default value |
The timezone of the new Coach. If not provided, defaults to match the API setting.
What to do if a Coach with the supplied email already exists.
S | Skip and return existing CoachID // default value |
A | Add anyway, return new CoachID |
E | Error out |
Send true if the new Coach should be sent an invite email immediately.
Subject line of the invite email to be sent (if opted for). If not included, will use template setting.
Body of the invite email to be sent (if opted for), [magicLink] is required. If not included, will use template setting.
ID of the Coach to be invited.
Subject line of the invite email to be sent. If not included, will use template setting.
Body of the invite email to be sent, [magicLink] is required. If not included, will use template setting.
ID of the Coach to be updated.
Whether or not to make this Coach's profile visible to clients.
Whether or not to make this Coach's home phone visible to clients.
Whether or not to make this Coach's work phone visible to clients.
Whether or not to make this Coach's cell phone visible to clients.
Whether or not to make this Coach's email address visible to clients.
Whether or not to make this Coach's address visible to clients.
ID of the Coach to be updated.
Whether or not this Coach is actively coaching Clients or just has an administrative role.
Allow Coach to add and modify her own Clients.
X | No access |
S | Self access |
A | Admin access |
Allow Coach to delete her own Clients.
X | No access |
S | Self access |
A | Admin access |
Allow Coach view access to all Clients.
X | Not granted |
A | Granted |
Allow Coach coaching access to all Clients, even if not specifically paired.
X | Not granted |
A | Granted |
Allow Coach to manage Coach/Client pairings.
X | Not granted |
A | Granted |
Allow Coach to add, edit, and delete other Coaches.
X | Not granted |
A | Granted |
Allow Coach to set administrative privileges of Coaches.
X | Not granted |
A | Granted |
Allow Coach to reassign ownership of share resources (Courses, Templates and Library Files)
X | Not granted |
A | Granted |
Allow Coach to manage appointment scheduling of self and/or others.
X | No access |
S | Self access |
A | Admin access |
Allow Coach to manage invoicing for own clients and/or others.
X | No access |
S | Self access |
A | Admin access |
Allow Coach to share Courses with the team.
X | Not granted |
A | Granted |
Allow Coach to clone Courses that have been shared with them.
X | Not granted |
A | Granted |
Allow Coach to share Worksheet and Session Templates with the team.
X | Not granted |
A | Granted |
Allow Coach to share Library Files with the team.
X | Not granted |
A | Granted |
Allow Coach to manage Coach membership for own Groups and/or Groups of others.
X | No access |
S | Self access |
A | Admin access |
Allow Coach view access to all Groups.
X | Not granted |
A | Granted |
Allow Coach manage team branding settings.
X | Not granted |
A | Granted |
Allow Coach to issue Client Agreements.
X | Not granted |
A | Granted |
Allow Coach to delete agreed-to Client Agreements.
X | Not granted |
A | Granted |
ID
, intfirstName
, stringlastName
, stringemail
, stringdateAdded
, date/timeisActive
, booleanhomePhone
, stringworkPhone
, stringcellPhone
, stringisRegistered
, booleanaddress1
, stringcity
, stringstate
, stringZIP
, stringavatarURL
, stringloginCount
, intlastLoginDate
, date/time or nullprofile
, an object of the following form...businessName
, stringbiography
, stringcredentials
, stringspecialty
, stringwebsite
, stringprofileExtra
, stringprofileShow
, booleanprofileShowEmail
, booleanprofileShowHomePhone
, booleanprofileShowWorkPhone
, booleanprofileShowCellPhone
, booleanprofileShowAddress
, booleanSet to true to include Coaches that are currently marked inactive.
C | Chronologically, newest first // default value |
A | Alphabetical, active first |
ID
, intfirstName
, stringlastName
, stringemail
, stringdateAdded
, date/timeisActive
, booleanhomePhone
, stringworkPhone
, stringcellPhone
, stringisRegistered
, booleanaddress1
, stringcity
, stringstate
, stringZIP
, stringloginCount
, intlastLoginDate
, date/time or nullprofile
, an object of the following form...businessName
, stringbiography
, stringcredentials
, stringspecialty
, stringwebsite
, stringprofileExtra
, stringprofileShow
, booleanprofileShowEmail
, booleanprofileShowHomePhone
, booleanprofileShowWorkPhone
, booleanprofileShowCellPhone
, booleanprofileShowAddress
, booleanClientID
, intThe ID of the coach who is to be the new client's primary coach.
M | Male |
F | Female |
U | Unspecified // default value |
The timezone of the new Client. If not provided, defaults to match her Coach's timezone.
The client's street address.
The client's city.
The client's state.
The client's ZIP or postal code.
What to do if a Client with the supplied email already exists.
S | Skip and return existing ClientID // default value |
A | Add anyway, return new ClientID |
E | Error out |
If alread at the limit, upgrade the account to make space for the new Client. If false, the call will return failure when there is no space.
Send true if the new client should be sent an invite email immediately.
Subject line of the invite email to be sent (if opted for). If not included, will use template setting.
Body of the invite email to be sent (if opted for), [magicLink] is required. If not included, will use template setting.
Any additional information you'd like to have on file, accessible at-a-glance.
Subject line of the invite email to be sent. If not included, will use template setting.
Body of the invite email to be sent, [magicLink] is required. If not included, will use template setting.
Setting true will grant continued, read-only access to the client.
If alread at the limit, upgrade the account to make space for the newly active Client. If false, the call will return failure when there is no space.
The timezone of the Client.
The client's street address.
The client's city.
The client's state.
The client's ZIP or postal code.
Any additional information you'd like to have on file, accessible at-a-glance.
ID
, intCoachID
, intfirstName
, stringlastName
, stringemail
, stringdateAdded
, date/timeisActive
, booleanisFreebie
, booleanhomePhone
, stringworkPhone
, stringcellPhone
, stringprofileExtra
, stringisRegistered
, booleanaddress1
, stringcity
, stringstate
, stringZIP
, stringloginCount
, intlastLoginDate
, date/time or nullCompanyID
, intcompanyName
, stringSet to true to include Clients that are currently marked inactive.
Get only Clients who are currently paired with a given Coach.
Get only Clients who are belong to a given Company. Provide a zero to get clients that don't belong to any Company.
C | Chronologically, newest first // default value |
A | Alphabetical, active first |
ID
, intCoachID
, intfirstName
, stringlastName
, stringemail
, stringdateAdded
, date/timeisActive
, booleanisFreebie
, booleanhomePhone
, stringworkPhone
, stringcellPhone
, stringprofileExtra
, stringisRegistered
, booleanaddress1
, stringcity
, stringstate
, stringZIP
, stringloginCount
, intlastLoginDate
, date/time or nullCompanyID
, intcompanyName
, stringID of the Coach to be paired with a Client.
ID of the Client to be paired with a Coach.
Clients always have exactly 1 Primary Coach, so switching to 'N', 'R' or 'C' will throw an error if doing so would leave the client without a Primary coach.
N | No access |
R | Read only access |
C | Coaching access // default value |
P | Coaching as Primary Coach |
ID of the Coach in the pairing to be deleted.
ID of the Client in the pairing to be deleted.
ClientID
, intclientName
, stringdateAdded
, date/timetype
, stringCoachID
, intcoachName
, stringdateAdded
, date/timetype
, stringID of the Client for whom pairings are to be gotten.
CoachID
, intClientID
, inttype
, stringstartDate
, date/timeendDate
, date/timeFilter the returned pairing history by coach.
Filter the returned pairing history by client.
Set to restrict Pairings returned to those starting at or after the provided value.
Set to restrict Pairings returned to those starting at or before the provided value.
ActionID
, intActionProjectID
, intID of the Client to whom this Action is to be assigned.
The ID of the Coach who is to be noted as assigning this action. Defaults to the Client's primary Coach.
A one-liner text of "what" the Action is.
Date on which the Action is to be done.
Time of day by which the Action is to be done.
Who's timezone the due date is in. Defaults to that of the assigning Coach.
C | coach |
L | client |
A | use API setting |
An optional additional comment about this Action.
Send true to notify the client via email of this new Action.
Name of the Project for the new Action to be filed under. If left blank the new Action will be a standalone one.
An alternative to projectName for specifying which project the new Action should be filed under.
Integer describing the relative significance of the Action within a project. Relevant only to Actions that are added to a project.
Prevent the Client from modifying or deleting the Action.
A semi-colon-separated list of comma-separated triplets, each defining a reminder. In a triplet, the first value defines who to send it to ([C]oach or c[L]ient),the second value defines the send method ([E]mail or [T]ext), and the third value defines when to send the reminder, as minutes relative to the due date.
L,E,1440 |
L,E,1440;L,E,120 |
L,T,60 |
L,E,1440;L,E,120;C,T,30 |
ID
, intActionProjectID
, int (zero for standalone Actions)action
, stringforWho
, "C" for Coach or "L" for ClientdateDue
, date/timedateDone
, date/time or nullisDone
, booleanisCanceled
, booleanreminderSet
, an array of items of the following form...ID
, intsendTo
, "C" for Coach or "L" for ClientsendMethod
, "E" for Email or "T" for TextrelativeMinutes
, intdateToSend
, date/timeisSent
, booleandateSent
, date/time or nullFilter a Client's Actions by which Coach assigned them.
Filter the Actions you get back down to a given project.
Set to true to include Actions that have already been marked complete.
Set to true to include Actions that have been canceled.
Set to true to include Actions that are for the coach to do.
ID
, intsendTo
, "C" for Coach or "L" for ClientsendMethod
, "E" for Email or "T" for TextrelativeMinutes
, intdateToSend
, date/timeisSent
, booleandateSent
, date/time or nullSet to true to include Reminders that have already been sent (otherwise just return future reminders, i.e. those yet to be sent.
A semi-colon-separated list of comma-separated triplets, each defining a reminder. In a triplet, the first value defines who to send it to ([C]oach or c[L]ient),the second value defines the send method ([E]mail or [T]ext), and the third value defines when to send the reminder, as minutes relative to the due date.
L,E,1440 |
L,E,1440;L,E,120 |
L,T,60 |
L,E,1440;L,E,120;C,T,30 |
Who's timezone the due date is in. Defaults to that of the assigning Coach.
C | coach |
L | client |
A | use API setting |
Name of the Project for the Aaction to be filed under. If set to "NULL" the Action will be changed to a standalone one.
An alternative to projectName for specifying which project the Action should be filed under.
Integer describing the relative significance of the Action within a project. Relevant only to Actions that are in a project.
Prevent the Client from modifying or deleting the Action.
Optionally specify when the Action was completed, otherwise defaults to the time of the call.
Optionally specify when the Action was completed, otherwise defaults to the time of the call.
Who's timezone the date done is in. Defaults to that of the assigning Coach.
C | coach |
L | client |
A | use API setting |
Optional comment to be posted on the Action as part of completing it. Will show as written by the assigning coach (or the client's primary coach if client-assigned).
ID
, intname
, stringdescription
, stringtotalWeight
, intdateAdded
, date/timedateModified
, date/time or nullThe ID of the Project you wish to delete.
Keep Actions within a Project around as standalone Actions. If false, delete any Actions within the Project.
MetricID
, intThe ID of the Client who will be tracking this Metric.
The unit of measure for numbers to be reported, like "$", "lbs", or "minutes".
The date at which tracking is to be done.
The date through which tracking is to be done.
Should a target apply for this Metric?
If a target, what should be the starting value?
If a target, what should be the endgin value?
Dictates how the graph is to be colored regarding being over/under the target values, if set.
H | Higher is better // default value |
L | Lower is better |
Cumulative means that numbers as reported are to be added to a running total.
R | Regular // default value |
C | Cumulative |
On what frequency should values be reported for this Metric?
none | on an arbitrary basis |
daily | every day |
bidaily | every other day |
weekdays | every weekday (Monday through Friday) // default value |
MWF | every Monday, Wednesday and Friday |
TR | every Tuesday and Thursday |
customWeekly | on select days of the week... |
weekly | weekly |
biweekly | biweekly |
monthlyDOM | monthly by date of month |
monthlyLastDOM | monthly on the last day of month |
monthlyDOW | monthly by day of week |
bimonthlyDOM | bimonthly by date of month |
bimonthlyDOW | bimonthly by day of week |
Shall a regular reminder be set for this Metric?
On which basis should reminders be sent?
DO | Day Of, as in send on days when reporting should happen |
DS | Days Since, as in send X days since data was last reported |
How shall the recurring reminders be sent to your client for this Metric?
E | Email // default value |
T | Text |
Time of day at which the reminder should be sent on called-for days.
Number of days since the last reporting that a reminder should be sent (applies only to the "DS" option for reminderMode).
ID
, intname
, stringunits
, stringtotalWeight
, intstartDate
, dateendDate
, datetargetMode
, char ([H]igher or [L]lower)targetStart
, numbertargetEnd
, numberdataMode
, char ([R]egular or [C]umulative)repeatRule
, stringdataSet
, an array of items of the following form...dateOf
, datevalue
, numbercomment
, stringThe Client whose Metrics are to be gotten.
Set to true to include Metrics that have already been marked complete, otherwise complete Metrics will be omitted.
ID of the Metric to which data is to be added.
Optional note about this data point.
ID of the Metric to which data is to be cleared.
ID of the Metric to be updated.
New name for the Metric, if to be changed.
The unit of measure for numbers to be reported, like "$", "lbs", or "minutes".
The date at which tracking is to be done.
The date through which tracking is to be done.
Should a target apply for this Metric?
If a target, what should be the starting value?
If a target, what should be the endgin value?
Dictates how the graph is to be colored regarding being over/under the target values, if set.
H | Higher is better |
L | Lower is better |
Cumulative means that numbers as reported are to be added to a running total.
R | Regular |
C | Cumulative |
On what frequency should values be reported for this Metric?
none | on an arbitrary basis |
daily | every day |
bidaily | every other day |
weekdays | every weekday (Monday through Friday) |
MWF | every Monday, Wednesday and Friday |
TR | every Tuesday and Thursday |
customWeekly | on select days of the week... |
weekly | weekly |
biweekly | biweekly |
monthlyDOM | monthly by date of month |
monthlyLastDOM | monthly on the last day of month |
monthlyDOW | monthly by day of week |
bimonthlyDOM | bimonthly by date of month |
bimonthlyDOW | bimonthly by day of week |
Shall a regular reminder be set for this Metric?
On which basis should reminders be sent?
DO | Day Of, as in send on days when reporting should happen |
DS | Days Since, as in send X days since data was last reported |
Send true to notify the client via email of this new Action.
E | |
T | Text |
Time of day at which the reminder should be sent on called-for days.
Number of days since the last reporting that a reminder should be sent (applies only to the "DS" option for reminderMode).
The ID of the Coach whom the Appointment Types are associated with.
The ID of the Coach whom the Appointment is with.
The ID of the Client whom the Appointment is with.
The ID of the Appointment Type that the Appointment is to be of
Optional alternate label for the appointment (overrides the Appointment Type's name)
Optional alternate location for the appointment (overrides the Appointment Type's location)
Optional alternate description for the appointment (overrides the Appointment Type's description)
Who's timezone the appointment date/time is in. Defaults to that of the Coach.
C | coach |
L | client |
A | use API setting |
Send true if the Client should be sent a notification email immediately.
Subject line of the notification email to be sent (if opted for). If not included, will use template setting.
Body of the notification email to be sent (if opted for). If not included, will use template setting.
A semi-colon-separated list of comma-separated triplets, each defining a reminder. In a triplet, the first value defines who to send it to ([C]oach or c[L]ient),the second value defines the send method ([E]mail or [T]ext), and the third value defines when to send the reminder, as minutes relative to the due date. Send "default" to set default reminders defined for the Appointment Type.
default |
L,E,1440 |
L,E,1440;L,E,120 |
L,T,60 |
L,E,1440;L,E,120;C,T,30 |
ID
, intCoachID
, intClientID
, intEngagementID
, int, when belonging to an Engagement, otherwise zerowhat
, stringstartDate
, date/timeendDate
, date/timestatus
, string, "A" for Active, "C" for Canceled, "P" for Pending request, "D" for Declined requestdateAdded
, date/timedateCanceled
, date/time or nulllocation
, stringdescription
, stringreminderSet
, an array of items of the following form...ID
, intsendTo
, "C" for Coach or "L" for ClientsendMethod
, "E" for Email or "T" for TextrelativeMinutes
, intdateToSend
, date/timeisSent
, booleandateSent
, date/time or nullFilter Appointments by Coach.
Filter Appointments by Client.
Filter Appointments by the Company that the Clients belong to.
Filter Appointments by name, supports partial matching on prefix.
Set to restrict Appointments returned to those starting at or after the provided value.
Set to restrict Appointments returned to those starting at or before the provided value.
Set to true to include Appointments which are still just pending requests.
Set to true to include Appointments that have been canceled.
Set to true to send a notification via email to the Client attendee of the Appointment.
Optional comment from the Coach to be sent as part of the cancelation email to the Client.
SessionID
, intThe ID of the Coach who is to be noted as writing this Session. Defaults to the Client's primary Coach.
* | Visible to coach and client // default value |
C | Visible to coaches only |
P | Visible to author only |
ID
, intCoachID
, intClientID
, intdateOf
, date/timetitle
, textcontent
, textisDraft
, booleananswerSet
, an array of items of the following form...name
, stringvalue
, stringnumberValue
, numberFilter Sessions by Client.
Filter a Client's Sessions by which Coach wrote them.
Set to restrict Sessions returned to those at or after the provided value.
Set to restrict Sessions returned to those at or before the provided value.
Set to true to include Sessions not yet marked complete.
* | Visible to coach and client // default value |
C | Visible to coaches only |
P | Visible to author only |
ID
, intCoachID
, intClientID
, inttitle
, stringcontent
, stringdateAssigned
, date/timedateDue
, date/timedateDone
, date/time or nullisDone
, booleananswerSet
, an array of items of the following form...name
, stringvalue
, stringnumberValue
, numberreminderSet
, an array of items of the following form...ID
, intsendTo
, "C" for Coach or "L" for ClientsendMethod
, "E" for Email or "T" for TextrelativeMinutes
, intdateToSend
, date/timeisSent
, booleandateSent
, date/time or nullFilter Worksheets by Client.
Filter Client Worksheets by which Coach assigned them.
Filter Client Worksheets by which Company they belong to.
Filter a Client's Worksheets by which title, prefixed.
Set to true to include the full HTML content of the Worksheet.
Set to true to include Worksheets not yet marked complete.
Set to filter Worksheet by when they were assigned.
Set to filter Worksheet by when they were assigned.
ID
, intsendTo
, "C" for Coach or "L" for ClientsendMethod
, "E" for Email or "T" for TextrelativeMinutes
, intdateToSend
, date/timeisSent
, booleandateSent
, date/time or nullSet to true to include Reminders that have already been sent (otherwise just return future reminders, i.e. those yet to be sent.
A semi-colon-separated list of comma-separated triplets, each defining a reminder. In a triplet, the first value defines who to send it to ([C]oach or c[L]ient),the second value defines the send method ([E]mail or [T]ext), and the third value defines when to send the reminder, as minutes relative to the due date.
L,E,1440 |
L,E,1440;L,E,120 |
L,T,60 |
L,E,1440;L,E,120;C,T,30 |
ID
, inttitle
, textcontent
, text (if requested)Filter Agreement Templates by which title, prefixed.
Set to true to include the full HTML content of the Agreement Templates.
AgreementID
, intThe ID of the Coach who is to be noted as issuing this Agreement. Defaults to the Client's primary Coach.
The ID of the Agreement Template to issue. Can be obtained from Agreement.getTemplates
Allows you to specify an alternate title for the Agreement. When omitted, will default to that specified by the Agreement Template.
ID
, intClientID
, intdateIssued
, date/timedateAgreed
, date/timetitle
, textcontent
, text (if requested)Filter to Agreements belonging to a specific client.
Filter Agreements by which title, prefixed.
Set to true to include the full HTML content of the Agreements.
Filter by Agreement status.
O | Outstanding |
A | Agreed-to // default value |
B | Both Outstanding and Agreed-to |
Set to restrict Agreements returned to those issued at or after the provided value.
Set to restrict Agreements returned to those issued at or before the provided value.
ClientFileID
, intThe ID of the Client with whom to share this File.
The ID of the Coach who is to be noted as sharing this File. Defaults to the Client's primary Coach.
Data of the file to be uploaded, MUST BE Base64 encoded.
ClientFileID
, intThe ID of the Client with whom to share this File.
The ID of the Coach who is to be noted as sharing this File. Defaults to the Client's primary Coach.
The URL of the link to share
InvoiceID
, intThe ID of the Client for whom this invoice is.
If omitted, the due date will be calculated based on the dateOf and your setting of how many days out invoices are due by default.
If not supplied, a logical next invoice number will be assigned. Letters are allowed, e.g. "A1002".
A percentage-based rate of tax to be applied, e.g. 7.5 means apply a 7.5% tax.
What to do if an Invoice with the supplied number already exists.
S | Skip and return existing InvoiceID // default value |
A | Add anyway, return new InvoiceID |
E | Error out |
The ISO 4217 3-letter code of the currency. If not supplied, or not among the chosen accepted currencies, the chosen primary currency will be assumed.
A newline-separated list of items. An item is comprised of the item label followed by a double colon followed by the price. For example: "One month of coaching::400"
One month of coaching::400 |
One month of coaching::400 Being a Baller 6-week Course::600 |
If set to "true", will try to collect full payment for the invoice immediately (using a client's card on file). To determine if the charge was successful, use Invoice.get.
The ID of the Invoice to be sent. Invoice Number also accepted when prefixed with a "#", e.g. "#1005".
If not supplied, will send to the client. By supplying a valid email address this call can send to any 3rd party.
L | The Client // default value |
C | The Client's primary Coach |
someone@example.com | An arbitrary email of a 3rd party |
An optional message to include as part of the invoice.
Thanks for your business! |
Please pay within the next 7 days. |
ID
, intinvoiceNumber
, stringdateOf
, datedateDue
, datecurrency
, stringamount
, numberamountPaid
, numbertaxRate
, numberClientID
, intfirstName
, stringlastName
, stringemail
, stringlineItemSet
, an array of items of the following form...item
, stringamount
, numberpaymentSet
, an array of items of the following form...datePaid
, date/timeamount
, numbermethod
, stringcheckNumber
, stringFilter invoices by client. If omitted, invoices for all Clients are returned.
Filter a Client's Invoices by a client's primary Coach.
Set to restrict Invoices returned to those at or after the provided value.
Set to restrict Invoices returned to those at or before the provided value.
ID
, intinvoiceNumber
, stringdateOf
, datedateDue
, datecurrency
, stringamount
, numberamountPaid
, numbertaxRate
, numberClientID
, intfirstName
, stringlastName
, stringemail
, stringlineItemSet
, an array of items of the following form...item
, stringamount
, numberpaymentSet
, an array of items of the following form...datePaid
, date/timeamount
, numbermethod
, stringcheckNumber
, stringThe ID of the Invoice to be updated. Invoice Number also accepted when prefixed with a "#", e.g. "#1005".
The ID of the Invoice to be updated. Invoice Number also accepted when prefixed with a "#", e.g. "#1005".
A new date of the Invoice, if it is to be changed.
A new number for the Invoice, if it is to be changed.
A percentage-based rate of tax to be applied, e.g. 7.5 means apply a 7.5% tax.
A newline-separated list of items. An item is comprised of the item label followed by a double colon followed by the price. For example: "One month of coaching::400"
One month of coaching::400 |
One month of coaching::400 Being a Baller 6-week Course::600 |
The ID of the Invoice to be deleted. Invoice Number also accepted when prefixed with a "#", e.g. "#1005".
ID
, intInvoiceID
, intinvoiceNumber
, stringdatePaid
, dateamount
, numbercurrency
, stringmethod
, stringcheckNumber
, stringSet to restrict Invoice Payments returned to those at or after the provided value.
Set to restrict Invoice Payments returned to those at or before the provided value.
PaymentID
, intThe ID of the Invoice to which the record of payment is to be added. Invoice Number also accepted when prefixed with a "#", e.g. "#1005".
Will fill in as the current time when not supplied. Future dates not allowed.
If not supplied, will assume "Credit Card"
Cash | Cash |
Check | Check |
Credit Card | Credit Card // default value |
Bank Transfer | Bank Transfer |
Other | Other |
Optional memo that will be saved when supplied and method="Check"
If not set to "true", will throw an error if the added payment results in a net overpay of the invoice.
The ID of the Invoice Payment which is to be deleted.
ID
, intname
, textmanagingCoachID
, intduration
, intallocationUnit
, stringallocation
, intEngagementID
, intThe ID of the Client for whom the Engagement is to be added.
The ID of the Engagement Template to be used to fill in the details of the new Engagement.
The ID of the Coach who is to be noted as managing the Engagement. Defaults to the managing coach specified by the Engagement Template.
The date that the Engagement is to begin. Defaults to today if not provided.
The date that the Engagement is to end. Defaults to the end date implied by the Engement Template's duration setting, either bounded or indefinite.
The initial allocation of the Engagement expressed as a number followed by a space followed by the unit, either "A" for Appointments or "H" for hours (e.g. "12 A" or "6 H"). Defaults to the value given by the Engement Template.
12 A |
6 H |
Setting this to true CAN trigger the immediate creation of one or more invoices. If the Client has a card on file that allows automatic billing, that can result in immediate charges. When false, no invoices will be sent for the Engagement until manually configured by editing the Engagement in-app.
Having a client be in multiple Engagements that overlap in time is USUALLY a bad idea. Set this to true to allow it anyway, otherwise CA will return a 440 error when it detects that adding this Engagement would cause an overlap.
The ID of the Coach who is to be noted as managing the Engagement.
If provided but set to an empty or otherwise invalid date, the Engagement will be set to continue indefinitely.
The new allocation of the Engagement expressed as a number followed by a space followed by the unit, either "A" for Appointments or "H" for hours (e.g. "12 A" or "6 H").
12 A |
6 H |
When should the Engagement be noted as having been completed?
E | As of the Engagement's end date |
U | As of the Engagement's last Appointment |
N | Now // default value |
ID
, inttype
, stringClientID
, intCompanyID
, intCoachID
, intwithName
, stringname
, stringstartDate
, dateendDate
, dateallocationUnits
, stringallocation
, intallocationUsedP
, intallocationUsedA
, intallocationUsedV
, intallocationPerClient
, intnextInvoiceDate
, dateisComplete
, booleanisCanceled
, booleandateClosed
, date/timedateAdded
, date/timeAppointmentSet
, an array of items of the following form...ID
, intCoachID
, intClientID
, intwhat
, stringstartDate
, date/timeendDate
, date/timestatus
, stringdateAdded
, date/timedateCanceled
, date/time or nullcountsInEngagement
, intFilter Engagements by Client.
Filter Engagements by Company.
Filter Engagements by the managing Coach.
Set to restrict Engagements returned to those with a start date at or after the provided value.
Set to restrict Engagements returned to those with a start date at or before the provided value.
Set to restrict Engagements returned to those with an end date at or after the provided value.
Set to restrict Engagements returned to those with an end date at or before the provided value.
Set to true to include Appointments which count towards the Engagement.
ID
, intCoachID
, intname
, stringprice
, numberblurb
, stringdescription
, stringnotifyEmail
, stringURL
, stringiframeURL
, stringscriptURL
, stringID
, intname
, stringURL
, stringiframeURL
, stringscriptURL
, stringOfferingSet
, an array of items of the following form...ID
, intCoachID
, intname
, stringprice
, numberblurb
, stringdescription
, stringID
, intCoachID
, intname
, stringdayDuration
, intitemTimeOption
, stringCourseParticipantID
, intThe ID of the Client to be added.
The ID of the Coach who is effectively assigning/running this Course Participation. If omitted, defaults to the Primary Coach of the provided ClientID.
The ID of the Course to which the Client is to be added.
A [future] date at which the Client is to start the Course. If not supplied (or not in the future) the Client will start the Course immediately.
Assuming an immediate start, you can supply startOnDay to jump a participant to some other Day in the Course [other than the usual Day 1 start].
Assuming an immediate start, you can have or skip items from the start day in the Course be dispatched (e.g. a Message set to go out at 9am if the Client is starting at 11am: should they get that message?).
The ID of the Participant to be paused.
Date at which the Participant is to resume the Course. Omit to pause indefinitely.
The ID of the Participant to be unpaused.
The ID of the Participant to be fast forwarded.
How many days to fast forward? Must be 1 or greater.
Should Course items during the fast-forward period be dispatched to this participant?
IF Course items during the fast-forward period should be dispatched, should notifications of them be sent to this participant? Ignored when dispatchItems is false.
The ID of the Participant to be rewound.
How many days to rewind? Must be 1 or greater.
Should Course items during the rewind period be deleted from this participant, so that they may be newly dispatched as the Course progresses the next time around?
The ID of the Participant to be removed.
Should already-dispatched Course Items be deleted as well?
ID
, intClientID
, intclientFirstName
, stringclientLastName
, stringstartDate
, datedayOf
, intisPaused
, booleanunpauseDate
, dateisComplete
, booleandateCompleted
, dateThe ID of the Course whose Participants are to be gotten.
Optionally filter by ID of the Client for whom Participations are to be gotten.
Include Participants whose Course timeline progression has already been completed.
ID
, intgroupName
, stringincludedMembers
, an array of items of the following form...ClientID
, intclientName
, stringstartDate
, datedayOf
, intisPaused
, booleanunpauseDate
, dateisComplete
, booleandateCompleted
, dateThe ID of the Course whose Participants are to be gotten.
Optionally filter by ID of the Group for whom Participations are to be gotten.
Include Participants whose Course timeline progression has already been completed.
CourseAvailabilityID
, intThe ID of the Client to make the Course availabile to.
The ID of the Coach who will be effectively assigning/running the Course Participation when commenced by the client. If omitted, defaults to the Primary Coach of the provided ClientID.
The ID of the Course that the Client is to have made available.
A [future] date at which the Client is be able to start the Course. If not supplied (or not in the future) the Course will be made available to the Client immediately.
ID
, intClientID
, intCourseID
, intclientFirstName
, stringclientLastName
, stringcourseName
, stringdateAdded
, datedateAvailable
, dateisUsed
, booleandateUsed
, dateID of the Client for whom Course Availabilities are to be gotten.
Include Course Availabilities which have already been used.
ID
, intClientID
, intCourseID
, intclientFirstName
, stringclientLastName
, stringcourseName
, stringdateAdded
, datedateAvailable
, dateisUsed
, booleandateUsed
, dateThe ID of the Course for which Client Availabilities are to be gotten.
Include Course Availabilities which have already been used.
The ID of the Course Availability to be removed.
ID
, intCoachID
, intname
, stringtype
, stringGroupClientID
, intThe ID of the Client to be added.
The ID of the Course to which the Client is to be added.
ID
, intClientID
, intclientFirstName
, stringclientLastName
, stringstartDate
, dateAddedisActive
, booleanThe ID of the Group whose Client Members are to be gotten.
Include Group Clients who are inactive.
The ID of the Group Client Member to be removed.
ID
, intCoachID
, intcoachFirstName
, stringcoachLastName
, stringisOwner
, booleanstartDate
, dateAddedisActive
, booleanThe ID of the Group whose Coach Members are to be gotten.
Include Group Coaches who are inactive.
ID
, intname
, stringdateAdded
, date/timeisActive
, booleanaddress1
, stringcity
, stringstate
, stringZIP
, stringcountry
, stringSet to true to include Companies that are marked inactive.
C | Chronologically, newest first // default value |
A | Alphabetical, active first |
ID
, intfirstName
, stringlastName
, stringemail
, stringdateAdded
, date/timeisActive
, booleanhomePhone
, stringworkPhone
, stringcellPhone
, stringprofileExtra
, stringisRegistered
, booleanaddress1
, stringcity
, stringstate
, stringZIP
, stringloginCount
, intlastLoginDate
, date/time or nullCompanyID
, intcompanyName
, stringSet to true to include Personnel that are marked inactive.
Get only Personnel who are with a given Company.
C | Chronologically, newest first // default value |
A | Alphabetical, active first |
data
, CSVThe name of the field to be fetched, either input name within a Form-based Worksheet, Metric name, or fedBy input name for a Metric.
The ID of the coach by which you may filter Clients (i.e. return data for Clients whose Primary Coach is this one). If omitted, data is returned for clients organization-wide.
The ID of the client for whom data is to be returned, if desired only for a single, specific client.
Set to restrict data returned to those dated at or after the provided value.
Set to restrict data returned to those dated at or before the provided value.
Include data for Clients who are inactive.
Set true to inclue the name of the Primary Coach for output Client records.
Group data dates to into weeks or months for a more coherent spreadsheet. Useful when, for example, clients all report on a weekly basis yet might do it on any day of the week.
D | Days |
W | Weeks // default value |
M | Months |
Data points often have a sensible textual and numeric value. Set this to get one, the other, or both.
N | Numeric values // default value |
T | Text values |
B | Both text and numeric values |
How should the returned data be structured in the CSV? Date Grid means each row is a client, and columns are dates of the data. Data Point Listing returns rows that are each a single data point: ClientID, client name, date, and value.
D | Date Grid // default value |
L | Data Point Listing |
data
, CSVThe ID of the coach by which you may filter Clients (i.e. return data for Clients whose Primary Coach is this one). If omitted, data is returned for clients organization-wide.
The ID of the client for whom data is to be returned, if desired only for a single, specific client.
The ID of the Group for whose client members data is to be returned.
The ID of the Company for whose client members data is to be returned.
The ID of the Engagement for whose client data is to be returned.
Group activity statistics according to your bucket size of choice.
D | Days |
W | Weeks // default value |
M | Months |
Q | Quarters |
Y | Years |
The lower bound of the date range to report stats on..
The upper bound of the date range to report stats on.
The types of items to be included, each letter signifies a single type. A for Action, M for Metric, P for Appointment, S for Session Note, W for Worksheet, J for Journal Entry, F for File, C for Comment.
Include data for Clients who are inactive.
Set true to inclue a totals column.
Set true to inclue an averages column.
firstName
, stringlasName
, stringemail
, stringusername
, string
The CoachAccountable API can return the following error codes. If an API call triggers an error,
the code of that error will ALWAYS be returned in the error
field of the returned JSON object.
There are a few things to bear in mind about error codes:
error
field of the returned JSON object will ALWAYS be present and ALWAYS have the value 0
.message
field of the returned JSON object will be set with a message about the error.message
returned by the API may NOT match the descriptions found in the listing below, as
they are often more specific including context-specific information about the call (e.g. for error 202 you'll
get a message back of the form "The function you are trying to call, [whateverYouPassedIn], does not exist."Right then. Here are all the error codes that the API may return to you.
101 | Missing API ID |
102 | Missing API Key |
103 | Invalid API ID |
104 | Invalid API Key |
105 | Account is not active |
106 | API not enabled |
201 | The "a" parameter (which indicates which function to call) is missing |
202 | The "a" parameter is invalid, i.e. specifies a function which does not exist |
301 | A required value was not supplied |
302 | An invalid entity ID was provided (like a non-existent ActionID or ClientID) |
303 | An invalid email was supplied |
304 | An invalid date was supplied |
305 | An invalid time was supplied |
306 | An invalid name was supplied |
311 | An unknown CoachID was supplied |
312 | The CoachID supplied references an inactive Coach |
313 | The CoachID supplied references an non-coaching Coach |
321 | A non-valid reminderSet value supplied (commma-separated triplet expected) |
322 | A non-valid parameter for a reminder was supplied |
401 | The Client already exists with the same email and so cannot be added |
402 | The [magicLink] tag was missing from the inviteMessage for the Client invitation |
403 | The Client invitation cannot be sent because the client has already registered |
404 | An attempt to add a Client, but no space to do so (and you haven't given permission to upgrade) |
405 | An attempt to update Client who owns their own account details |
411 | The Coach already exists with the same email and so cannot be added |
412 | The [magicLink] tag was missing from the inviteMessage for the Coach invitation |
413 | The Coach invitation cannot be sent because the Coach has already registered |
414 | The Coach who owns the account cannot be deleted or deactivated |
415 | A coach who is still the Primary Coach for one or more Clients cannot be deleted or deactivated |
416 | The account owner cannot have permissions set via the API |
420 | The Action cannot be canceled for it was previously marked complete |
421 | The Action cannot be marked complete for it was previously canceled |
430 | The Metric is part of a Group or Coures and thus not fully editable |
431 | The Metric data is for an invalid date and thus cannot be added |
440 | The Client already has an Engagement that overlaps with this one |
441 | The Engagement cannot be marked complete for it is already canceled. |
442 | The Engagement cannot be canceled for it is already marked complete. |
443 | Invalid or missing value for Engagement allocation. |
470 | The provided fileData is too large |
471 | The provided fileData will not fit within the storage limits of the account |
472 | The provided URL is not valid |
481 | The Client is already an active participant in the Course |
482 | The Client cannot have the Coach be the assigning party for the Course |
483 | The Course Participation is already paused or unpaused |
491 | The Invoice already exists with the same number and so cannot be added |
492 | The Invoice cannot be created without specifying one or more line items |
493 | A non-valid lineItemSet value was supplied (newline-separated line items expected) |
494 | A non-valid parameter for a line item was supplied ([label]::[amount] is the expected format) |
495 | A non-valid sendTo value was supplied (should be a valid email if not L or C) |
496 | A non-valid amount was supplied (should be above zero and probably not exceed the balance) |
497 | A non-valid dateOf was supplied (cannot be in the future) |
498 | The Client is inactive |
Here's some code to get you started talking to the API with PHP:
<?php
APITestDrive();
function APITestDrive() {
// Get all of our clients:
$result = CallCoachAccountableAPI("Client.getAll");
$clientSet = $result['return'];
if($clientCount = count($clientSet) == 0) {
echo "Ah, no clients at all! This will not be a very good demo...";
return;
}
echo "We got $clientCount client" . ($clientCount == 1 ? '' : 's') . " back! They are:<br />";
foreach($clientSet as $client) {
echo $client['firstName'] . ' ' . $client['lastName'] . '<br />';
}
echo "<br />Let's assign a new action to {$clientSet[0]['firstName']}...<br />";
// Now add an Action to the first client in the list:
$ClientID = $clientSet[0]['ID'];
$response = CallCoachAccountableAPI("Action.add", [
'ClientID' => $ClientID,
'theAction' => 'Test the API',
'dateDue' => '4/5/2025', // give 'em plenty of time to finish :)
'timeDue' => '3:32pm',
'reminderSet'=> "L,T,1440;C,E,20" // c[L]ient gets a [T]ext 1 day before (60*24 minutes),
// [C]oach gets an [E]mail 20 minutes before
]);
$ActionID = $response['return']['ActionID'];
echo "Action $ActionID added successfully!<br />";
// Now mark it done:
$response = CallCoachAccountableAPI("Action.markDone", array('ActionID' => $ActionID));
echo "Successfully marked Action $ActionID done!<br />"; // assumed because no exception was thrown
echo "<br />And there you have it. :)";
}
function CallCoachAccountableAPI($functionName, $params = array(), $throwExceptionOnAPIError = true) {
$APIURL= "https://www.coachaccountable.com/API/";
// Fill in these for your account, or fetch from whatever source is appropriate
$APIID = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
$APIKey= "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
$postData = array_merge($params, array(
'a' => $functionName,
'APIID' => $APIID,
'APIKey' => $APIKey,
));
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $APIURL);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);
// A nice shortcut but you SHOULDN'T need this, see http://php.net/manual/en/function.curl-setopt.php#110457
// Uncomment this only if you can't be bothered to do a more properly secure setup of your PHP environment.
// curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
$result = null; // for now
try {
$rawResult = curl_exec($ch);
$response = curl_getinfo($ch);
// Let's see how we did:
if($response['http_code'] != 200) // the HTTP request itself failed for whatever reason:
throw new Exception('HTTP failure returns from curl_exec', $response['http_code']);
// Did we get valid JSON back as expected?
$result = json_decode($rawResult, true);
if(!$result)
throw new Exception('API response not valid/decodable JSON data');
// So far so good. How about an API-specific error?
// Depending on your style you can either have this low level code throw an Exception when there is one,
// OR you can handle it in the returned $result as you see fit:
if($throwExceptionOnAPIError && $result['error'])
throw new Exception($result['message'], $result['error']); // the API defines specific error codes
// If we're still here we're all good! We'll return the JSON $result back to the caller as expected.
} catch (HttpException $ex) {
throw $ex; // throw it like any other, but you might want to do something differently here
} finally {
curl_close($ch);
}
return $result;
}
At least there certainly can be, and quickly.
The API as it exists is completely driven by user requests, folks just like you asking "Hey, can I do X using the API?".
We have and will continue to evolve the API to meet the needs that users express.
So if there's something you want to be able to do with the API but there isn't the functionality to let you do so, speak up and let it be known!
You can send a support request to get in touch.