Welcome to the CoachAccountable API
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.
Getting Around
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!
How to call the API
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:
Here's an example of a return JSON object:
{
"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 sent
return
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.
Coach
Coach.add
Return values:
CoachID, intDescription:
Add a new Coach to your Team accountParameters:
| M | 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.
Coach.invite
Description:
Send Coach an invitation email.Parameters:
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.
Coach.deactivate
Description:
Deactivate an existing Coach. Coach data remains but the Coach can no longer log in. Fails if the Coach is the Primary Coach to one or more Clients.Coach.activate
Description:
Reactivate an inactive Coach.Coach.updateProfile
Description:
Update one or more fields/settings of the profile of a given Coach. Omitted fields will remain as they were.Parameters:
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.
Coach.setPermissions
Description:
Update one or more of the permission settings for a given Coach.Parameters:
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 |
Coach.delete
Description:
Delete a Coach. Cannot be undone, so call this with care! Fails if the Coach is the Primary Coach to one or more Clients.Coach.getAll
Return values:
An array of zero or more items of the following form...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, booleanDescription:
Get a listing of all CoachesParameters:
Set to true to include Coaches that are currently marked inactive.
| C | Chronologically, newest first // default value |
| A | Alphabetical, active first |
Coach.get
Return values:
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, booleanDescription:
Get basic information for a single CoachClient
Client.add
Return values:
ClientID, intDescription:
Add a new client to your accountParameters:
The 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.
| NA | Never Allowed |
| AUE | Allowed Unless Engagement says otherwise |
| ABE | Allowed only By Engagement |
| D | Defer to organization-wide setting // default value |
Client.invite
Description:
Send Client an invitation email.Parameters:
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.
Client.deactivate
Description:
Deactivate an existing client. Makes space for new ones but means this client can no longer log in (unless mayAccessWhenInactive is set to true, in which case they CAN log in but with merely read-only access!).Parameters:
Setting true will grant continued, read-only access to the client.
Client.activate
Description:
Reactivate an inactive client.Parameters:
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.
Client.update
Description:
Update basic information about a clientParameters:
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.
| NA | Never Allowed |
| AUE | Allowed Unless Engagement says otherwise |
| ABE | Allowed only By Engagement |
| D | Defer to organization-wide setting // default value |
Client.setProfileExtra
Description:
Update a client's extra profile information.Parameters:
Any additional information you'd like to have on file, accessible at-a-glance.
Client.delete
Description:
Delete a Client. Cannot be undone, so call this with care!Client.getAll
Return values:
An array of zero or more items of the following form...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, stringDescription:
Get a listing of all ClientsParameters:
Set 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 |
Client.get
Return values:
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, stringDescription:
Get basic information for a single ClientPairing
Pairing.set
Description:
Create, update, or remove a Pairing between Coach and Client.Parameters:
ID 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 |
Pairing.delete
Description:
Delete a Pairing between Coach and Client. This function is effectively an alias passing type="N" to Pairing.set. Fails if the Coach is the Client's primary coach.Parameters:
ID of the Coach in the pairing to be deleted.
ID of the Client in the pairing to be deleted.
Pairing.getForCoach
Return values:
An array of zero or more items of the following form...ClientID, intclientName, stringdateAdded, date/timetype, stringDescription:
Get a listing of all Client Pairings with a given CoachPairing.getForClient
Return values:
An array of zero or more items of the following form...CoachID, intcoachName, stringdateAdded, date/timetype, stringDescription:
Get a listing of all Coach Pairings with a given ClientParameters:
ID of the Client for whom pairings are to be gotten.
Pairing.getHistory
Return values:
An array of zero or more items of the following form...CoachID, intClientID, inttype, stringstartDate, date/timeendDate, date/timeDescription:
Get the history of Pairings between coaches and clients.Parameters:
Filter 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.
Action
Action.add
Return values:
ActionID, intActionProjectID, intDescription:
Add a new Action for a ClientParameters:
ID 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 |
Action.getAll
Return values:
An array of zero or more items of the following form...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 nullDescription:
Get the Actions for a given ClientParameters:
Filter 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.
Action.getReminders
Return values:
An array of zero or more 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 nullDescription:
Get the reminders set for a given ActionParameters:
Set to true to include Reminders that have already been sent (otherwise just return future reminders, i.e. those yet to be sent.
Action.setReminders
Description:
Set the reminders set for a given Action, overwriting whatever was set previouslyParameters:
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 |
Action.clearReminders
Description:
Delete all unsent reminders for a given ActionAction.deleteReminder
Description:
Delete a particular Reminder for a given ActionAction.update
Description:
Update an Action. Any fields you provide will be used for the update, and any you omit will remain unchanged.Parameters:
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.
Action.markDone
Description:
Mark an Action completeParameters:
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).
Action.unmarkDone
Description:
Unmark an Action completeAction.uncancel
Description:
Undo the cancelation of a canceled ActionAction.getAllProjects
Return values:
An array of zero or more items of the following form...ID, intname, stringdescription, stringtotalWeight, intdateAdded, date/timedateModified, date/time or nullDescription:
Fetch a listing of projects for a given ClientAction.deleteProject
Description:
Delete an Action Project for a given ClientParameters:
The 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.
Metric
Metric.add
Return values:
MetricID, intDescription:
Create a new Metric for a ClientParameters:
The 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).
Metric.getAll
Return values:
An array of zero or more items of the following form...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, stringDescription:
Get the Metrics for a given ClientParameters:
The 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.
Metric.addData
Description:
Add a data point to a given Metric for a given dayParameters:
ID of the Metric to which data is to be added.
Optional note about this data point.
Metric.clearDayData
Description:
Remove a Metric data point for a given dayParameters:
ID of the Metric to which data is to be cleared.
Metric.update
Description:
Update a Metric. Any fields you provide will be used for the update, and any you omit will remain unchanged.Parameters:
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).
Metric.markComplete
Description:
Mark a Metric completeMetric.unmarkComplete
Description:
Unmark a Metric completeMetric.delete
Description:
Delete a MetricAppointment
Appointment.getTypes
Description:
Get the collection of Appointment Types availableParameters:
The ID of the Coach whom the Appointment Types are associated with.
Appointment.add
Description:
Add a new Appointment between Coach and ClientParameters:
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 |
Appointment.getAll
Return values:
An array of zero or more items of the following form...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 nullDescription:
Get Appointments for a given Coach/ClientParameters:
Filter 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.
Appointment.cancel
Description:
Cancel an AppointmentParameters:
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.
Appointment.delete
Description:
Delete an AppointmentSession
Session.add
Return values:
SessionID, intDescription:
Add a new Session for a ClientParameters:
The 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 |
Session.getAll
Return values:
An array of zero or more items of the following form...ID, intCoachID, intClientID, intdateOf, date/timetitle, textcontent, textisDraft, booleananswerSet, an array of items of the following form...name, stringvalue, stringnumberValue, numberDescription:
Get the Sessions for a given ClientParameters:
Filter 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.
Session.update
Description:
Update a Session. Any fields you provide will be used for the update, and any you omit will remain unchanged.Parameters:
| * | Visible to coach and client // default value |
| C | Visible to coaches only |
| P | Visible to author only |
Worksheet
Worksheet.getAll
Return values:
An array of zero or more items of the following form...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 nullDescription:
Get the Worksheets for a given Client, or for all clients. Returns at most the 500 most recently assigned, or 1000 if you don't include content.Parameters:
Filter 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.
Worksheet.getReminders
Return values:
An array of zero or more 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 nullDescription:
Get the reminders set for a given WorksheetParameters:
Set to true to include Reminders that have already been sent (otherwise just return future reminders, i.e. those yet to be sent.
Worksheet.setReminders
Description:
Set the reminders set for a given Worksheet, overwriting whatever was set previouslyParameters:
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 |
Worksheet.clearReminders
Description:
Delete all unsent reminders for a given WorksheetWorksheet.deleteReminder
Description:
Delete a particular Reminder for a given WorksheetAgreement
Agreement.getTemplates
Return values:
An array of zero or more items of the following form...ID, inttitle, textcontent, text (if requested)Description:
Get the Agreement Templates available for issuing to clientsParameters:
Filter Agreement Templates by which title, prefixed.
Set to true to include the full HTML content of the Agreement Templates.
Agreement.issue
Return values:
AgreementID, intDescription:
Issue a new Agreement for a ClientParameters:
The 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.
Agreement.getAll
Return values:
An array of zero or more items of the following form...ID, intClientID, intdateIssued, date/timedateAgreed, date/timetitle, textcontent, text (if requested)Description:
Get the Agreements on file for one or all ClientsParameters:
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.
Agreement.delete
Description:
Delete an AgreementClientFile
ClientFile.addAsUpload
Return values:
ClientFileID, intDescription:
Add a file shared with a ClientParameters:
The 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.
ClientFile.addAsURL
Return values:
ClientFileID, intDescription:
Add a file shared with a Client as an external URLParameters:
The 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
Invoice
Invoice.add
Return values:
InvoiceID, intDescription:
Add a new Invoice for a ClientParameters:
The 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.
Invoice.send
Description:
Send a Client their Invoice via email.Parameters:
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. |
Invoice.getAll
Return values:
An array of zero or more items of the following form...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, stringDescription:
Get the Invoices for a given ClientParameters:
Filter 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.
Invoice.get
Return values:
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, stringDescription:
Get a given InvoiceParameters:
The ID of the Invoice to be updated. Invoice Number also accepted when prefixed with a "#", e.g. "#1005".
Invoice.update
Description:
Update an Invoice. Any fields you provide will be used for the update, and any you omit will remain unchanged.Parameters:
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 |
Invoice.delete
Description:
Delete an InvoiceParameters:
The ID of the Invoice to be deleted. Invoice Number also accepted when prefixed with a "#", e.g. "#1005".
Invoice.getPayments
Return values:
An array of zero or more items of the following form...ID, intInvoiceID, intinvoiceNumber, stringdatePaid, dateamount, numbercurrency, stringmethod, stringcheckNumber, stringDescription:
Get Invoice PaymentsParameters:
Set 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.
Invoice.addPayment
Return values:
PaymentID, intDescription:
Record a Payment on a given InvoiceParameters:
The 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.
Invoice.deletePayment
Description:
Delete a Payment on a given InvoiceParameters:
The ID of the Invoice Payment which is to be deleted.
Engagement
Engagement.getTemplates
Return values:
An array of zero or more items of the following form...ID, intname, textmanagingCoachID, intduration, intallocationUnit, stringallocation, intDescription:
Get the Engagement Templates available.Parameters:
try this...Engagement.addForClient
Return values:
EngagementID, intDescription:
Add a new Engagement for a Client.Parameters:
The 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.
Engagement.update
Description:
Update an Engagement. Any fields you provide will be used for the update, and any you omit will remain unchanged.Parameters:
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 |
Engagement.complete
Description:
Delete an EngagementParameters:
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 |
Engagement.cancel
Description:
Delete an EngagementEngagement.reopen
Description:
Re-open a canceled or completed EngagementEngagement.delete
Description:
Delete an EngagementEngagement.getAll
Return values:
An array of zero or more items of the following form...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, intDescription:
Get the Engagements for a given Client or Company.allocationUnit is given as either "A" for Appointments, or "M" for Minutes, and the integer value for allocation will be in those units.
If includeAppointments, the countsInEngagement value in the AppointmentSet entries will be:
- 1 when it affirmatively counts,
- -1 when manually marked as not counting, and
- 0 when neither judgement has been applied (manually or automatically).
allocationPerClient pertains only to Company Engagements (i.e. when CompanyID > 0), and will always be zero for Client Engagements. A value of zero means no per-client limit.
Note: When filtereing by ClientID, in addition Engagements that are specific to that Client you will also get back any Company Engagements that that Client happens to be a part of. If you opt to includeAppointments, the Appointments returned for that Engagement will be filtered down to just those of the provided ClientID.
Parameters:
Filter 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.
Offering
Offering.getAll
Return values:
An array of zero or more items of the following form...ID, intCoachID, intname, stringprice, numberblurb, stringdescription, stringnotifyEmail, stringURL, stringiframeURL, stringscriptURL, stringDescription:
Get the Offerings currently configured.Parameters:
try this...OfferingCollection
OfferingCollection.getAll
Return values:
An array of zero or more items of the following form...ID, intname, stringURL, stringiframeURL, stringscriptURL, stringOfferingSet, an array of items of the following form...ID, intCoachID, intname, stringprice, numberblurb, stringdescription, stringDescription:
Get the Offering Collections currently configured.Parameters:
try this...Course
Course.getAll
Return values:
An array of zero or more items of the following form...ID, intCoachID, intname, stringdayDuration, intitemTimeOption, stringDescription:
Get the Courses available for Clients to be added to.Course.addClientParticipant
Return values:
CourseParticipantID, intDescription:
Add a Client as a participant in a CourseParameters:
The 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?).
Course.pauseParticipant
Description:
Pause a participation along the timeline of its respective CourseParameters:
The ID of the Participant to be paused.
Date at which the Participant is to resume the Course. Omit to pause indefinitely.
Course.unpauseParticipant
Description:
Resume a participation along the timeline of its respective CourseParameters:
The ID of the Participant to be unpaused.
Course.fastForwardParticipant
Description:
Fast forward a participation along the timeline of its respective CourseParameters:
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.
Course.rewindParticipant
Description:
Rewind a participation along the timeline of its respective CourseParameters:
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?
Course.stopParticipant
Description:
Remove a participation from its respective CourseParameters:
The ID of the Participant to be removed.
Should already-dispatched Course Items be deleted as well?
Course.getAllClientParticipants
Return values:
An array of zero or more items of the following form...ID, intClientID, intclientFirstName, stringclientLastName, stringstartDate, datedayOf, intisPaused, booleanunpauseDate, dateisComplete, booleandateCompleted, dateDescription:
Get the Participants for a given CourseParameters:
The 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.
Course.getAllGroupParticipants
Return values:
An array of zero or more items of the following form...ID, intgroupName, stringincludedMembers, an array of items of the following form...ClientID, intclientName, stringstartDate, datedayOf, intisPaused, booleanunpauseDate, dateisComplete, booleandateCompleted, dateDescription:
Get the Group Participants for a given CourseParameters:
The 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.
Course.addClientAvailability
Return values:
CourseAvailabilityID, intDescription:
Add Availability of a Course to a ClientParameters:
The 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.
Course.getAvailabilitiesForClient
Return values:
An array of zero or more items of the following form...ID, intClientID, intCourseID, intclientFirstName, stringclientLastName, stringcourseName, stringdateAdded, datedateAvailable, dateisUsed, booleandateUsed, dateDescription:
Get the Courses Available to a given ClientParameters:
ID of the Client for whom Course Availabilities are to be gotten.
Include Course Availabilities which have already been used.
Course.getAvailabilitiesForCourse
Return values:
An array of zero or more items of the following form...ID, intClientID, intCourseID, intclientFirstName, stringclientLastName, stringcourseName, stringdateAdded, datedateAvailable, dateisUsed, booleandateUsed, dateDescription:
Get the Participants for a given CourseParameters:
The ID of the Course for which Client Availabilities are to be gotten.
Include Course Availabilities which have already been used.
Course.removeClientAvailability
Description:
Make a Course no longer available to a clientParameters:
The ID of the Course Availability to be removed.
Group
Group.getAll
Return values:
An array of zero or more items of the following form...ID, intCoachID, intname, stringtype, stringDescription:
Get the Groups available for Clients to be added to.Group.addClientMember
Return values:
GroupClientID, intDescription:
Add a Client as a member in a GroupParameters:
The ID of the Client to be added.
The ID of the Course to which the Client is to be added.
Group.getAllClientMembers
Return values:
An array of zero or more items of the following form...ID, intClientID, intclientFirstName, stringclientLastName, stringstartDate, dateAddedisActive, booleanDescription:
Get the Client Members for a given GroupParameters:
The ID of the Group whose Client Members are to be gotten.
Include Group Clients who are inactive.
Group.deactivateClientMember
Description:
Deactivate an existing Client Member's participation within a Group.Group.activateClientMember
Description:
Reactivate an inactive Client Member's participation within a Group.Group.removeClientMember
Description:
Remove a Client from a GroupParameters:
The ID of the Group Client Member to be removed.
Group.getAllCoachMembers
Return values:
An array of zero or more items of the following form...ID, intCoachID, intcoachFirstName, stringcoachLastName, stringisOwner, booleanstartDate, dateAddedisActive, booleanDescription:
Get the Coach Members for a given GroupParameters:
The ID of the Group whose Coach Members are to be gotten.
Include Group Coaches who are inactive.
Company
Company.getAll
Return values:
An array of zero or more items of the following form...ID, intname, stringdateAdded, date/timeisActive, booleanaddress1, stringcity, stringstate, stringZIP, stringcountry, stringDescription:
Get a listing of all CompaniesParameters:
Set to true to include Companies that are marked inactive.
| C | Chronologically, newest first // default value |
| A | Alphabetical, active first |
Personnel
Personnel.getAll
Return values:
An array of zero or more items of the following form...ID, intfirstName, stringlastName, stringemail, stringdateAdded, date/timeisActive, booleanhomePhone, stringworkPhone, stringcellPhone, stringprofileExtra, stringisRegistered, booleanaddress1, stringcity, stringstate, stringZIP, stringloginCount, intlastLoginDate, date/time or nullCompanyID, intcompanyName, stringDescription:
Get a listing of all PersonnelParameters:
Set 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 |
ClientData
ClientData.getByField
Return values:
data, CSVDescription:
Get a CSV-formatted spreadsheet of client data for a given field nameParameters:
The 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 |
ClientData.getActivityStats
Return values:
data, CSVDescription:
Get a CSV-formatted spreadsheet of client activity stats for a given date range.Parameters:
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.
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.
Account
Account.me
Return values:
firstName, stringlasName, stringemail, stringusername, stringDescription:
Get basic information about your account.Parameters:
try this...Error Codes
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:
- Getting an error code back in this manner means the HTTP request itself was successful (i.e. HTTP 200 status code on the request).
- For successful calls, the
errorfield of the returned JSON object will ALWAYS be present and ALWAYS have the value0. - Non-zero values are sufficient to indicate that the there as an API-level error with the call, and no action was performed.
- When an error is present, the
messagefield of the returned JSON object will be set with a message about the error. - Please note that the
messagereturned 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 |
Sample Code
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;
}
There's more to the API
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.