Loading...

Table of Contents

Introduction How to call the API

Coach Coach.add Coach.invite Coach.deactivate Coach.activate Coach.updateProfile Coach.setPermissions Coach.delete Coach.getAll Coach.get Client Client.add Client.invite Client.deactivate Client.activate Client.update Client.setProfileExtra Client.delete Client.getAll Client.get Pairing Pairing.set Pairing.delete Pairing.getForCoach Pairing.getForClient Pairing.getHistory Action Action.add Action.getAll Action.getReminders Action.setReminders Action.clearReminders Action.deleteReminder Action.update Action.delete Action.markDone Action.unmarkDone Action.cancel Action.uncancel Action.getAllProjects Action.deleteProject Metric Metric.add Metric.getAll Metric.addData Metric.clearDayData Metric.update Metric.markComplete Metric.unmarkComplete Metric.delete Appointment Appointment.getTypes Appointment.add Appointment.getAll Appointment.cancel Appointment.delete Session Session.add Session.getAll Session.update Session.delete Worksheet Worksheet.getAll Worksheet.getReminders Worksheet.setReminders Worksheet.clearReminders Worksheet.deleteReminder Worksheet.delete Agreement Agreement.getTemplates Agreement.issue Agreement.getAll Agreement.delete ClientFile ClientFile.addAsUpload ClientFile.addAsURL Invoice Invoice.add Invoice.send Invoice.getAll Invoice.get Invoice.update Invoice.delete Invoice.getPayments Invoice.addPayment Invoice.deletePayment Engagement Engagement.getTemplates Engagement.addForClient Engagement.update Engagement.complete Engagement.cancel Engagement.reopen Engagement.delete Engagement.getAll Offering Offering.getAll OfferingCollection OfferingCollection.getAll Course Course.getAll Course.addClientParticipant Course.pauseParticipant Course.unpauseParticipant Course.fastForwardParticipant Course.rewindParticipant Course.stopParticipant Course.getAllClientParticipants Course.getAllGroupParticipants Course.addClientAvailability Course.getAvailabilitiesForClient Course.getAvailabilitiesForCourse Course.removeClientAvailability Group Group.getAll Group.addClientMember Group.getAllClientMembers Group.deactivateClientMember Group.activateClientMember Group.removeClientMember Group.getAllCoachMembers Company Company.getAll Personnel Personnel.getAll ClientData ClientData.getByField ClientData.getActivityStats Account Account.me Error Codes Sample Code But wait... ...there's more!


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!
John signed.

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:

status
result
return
error
message

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:

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, int

Description:

Add a new Coach to your Team account

Parameters:

firstName  string   (required, maxlength 50)
lastName  string   (required, maxlength 50)
email  string   (required, maxlength 50)
homePhone  string   (maxlength 20)
cellPhone  string   (maxlength 20)
workPhone  string   (maxlength 20)
gender  enum   (defaults to U)
Accepted Values:
MMale
FFemale
UUnspecified     // default value
timezone  string  

The timezone of the new Coach. If not provided, defaults to match the API setting.

onDuplicateEmail  enum   (defaults to S)

What to do if a Coach with the supplied email already exists.

Accepted Values:
SSkip and return existing CoachID     // default value
AAdd anyway, return new CoachID
EError out
sendInvite  boolean   (defaults to false)

Send true if the new Coach should be sent an invite email immediately.

inviteSubject  string  

Subject line of the invite email to be sent (if opted for). If not included, will use template setting.

inviteMessage  string  

Body of the invite email to be sent (if opted for), [magicLink] is required. If not included, will use template setting.

try this...

Coach.invite

Description:

Send Coach an invitation email.

Parameters:

CoachID  int   (required)

ID of the Coach to be invited.

inviteSubject  string  

Subject line of the invite email to be sent. If not included, will use template setting.

inviteMessage  string  

Body of the invite email to be sent, [magicLink] is required. If not included, will use template setting.

try this...

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.

Parameters:

CoachID  int   (required)

ID of the Coach to be deactivated.

try this...

Coach.activate

Description:

Reactivate an inactive Coach.

Parameters:

CoachID  int   (required)

ID of the Coach to be reactivated.

try this...

Coach.updateProfile

Description:

Update one or more fields/settings of the profile of a given Coach. Omitted fields will remain as they were.

Parameters:

CoachID  int   (required)

ID of the Coach to be updated.

businessName  string  
website  string  
specialty  string  
credentials  string  
biography  string  
profileExtra  string  
profileShow  boolean   (defaults to true)

Whether or not to make this Coach's profile visible to clients.

profileShowHomePhone  boolean   (defaults to true)

Whether or not to make this Coach's home phone visible to clients.

profileShowWorkPhone  boolean   (defaults to true)

Whether or not to make this Coach's work phone visible to clients.

profileShowCellPhone  boolean   (defaults to true)

Whether or not to make this Coach's cell phone visible to clients.

profileShowEmail  boolean   (defaults to true)

Whether or not to make this Coach's email address visible to clients.

profileShowAddress  boolean   (defaults to true)

Whether or not to make this Coach's address visible to clients.

try this...

Coach.setPermissions

Description:

Update one or more of the permission settings for a given Coach.

Parameters:

CoachID  int   (required)

ID of the Coach to be updated.

isCoaching  boolean  

Whether or not this Coach is actively coaching Clients or just has an administrative role.

Client.manage  enum  

Allow Coach to add and modify her own Clients.

Accepted Values:
XNo access
SSelf access
AAdmin access
Client.delete  enum  

Allow Coach to delete her own Clients.

Accepted Values:
XNo access
SSelf access
AAdmin access
Client.view  enum  

Allow Coach view access to all Clients.

Accepted Values:
XNot granted
AGranted
Client.coach  enum  

Allow Coach coaching access to all Clients, even if not specifically paired.

Accepted Values:
XNot granted
AGranted
Client.pair  enum  

Allow Coach to manage Coach/Client pairings.

Accepted Values:
XNot granted
AGranted
Coach.manage  enum  

Allow Coach to add, edit, and delete other Coaches.

Accepted Values:
XNot granted
AGranted
Admin.manage  enum  

Allow Coach to set administrative privileges of Coaches.

Accepted Values:
XNot granted
AGranted
Admin.resourceOwnership  enum  

Allow Coach to reassign ownership of share resources (Courses, Templates and Library Files)

Accepted Values:
XNot granted
AGranted
Appointment.manage  enum  

Allow Coach to manage appointment scheduling of self and/or others.

Accepted Values:
XNo access
SSelf access
AAdmin access
Invoice.manage  enum  

Allow Coach to manage invoicing for own clients and/or others.

Accepted Values:
XNo access
SSelf access
AAdmin access
Course.share  enum  

Allow Coach to share Courses with the team.

Accepted Values:
XNot granted
AGranted
Course.clone  enum  

Allow Coach to clone Courses that have been shared with them.

Accepted Values:
XNot granted
AGranted
Template.share  enum  

Allow Coach to share Worksheet and Session Templates with the team.

Accepted Values:
XNot granted
AGranted
LibraryFile.share  enum  

Allow Coach to share Library Files with the team.

Accepted Values:
XNot granted
AGranted
Group.manage  enum  

Allow Coach to manage Coach membership for own Groups and/or Groups of others.

Accepted Values:
XNo access
SSelf access
AAdmin access
Group.view  enum  

Allow Coach view access to all Groups.

Accepted Values:
XNot granted
AGranted
Branding.manage  enum  

Allow Coach manage team branding settings.

Accepted Values:
XNot granted
AGranted
Agreement.manage  enum  

Allow Coach to issue Client Agreements.

Accepted Values:
XNot granted
AGranted
Agreement.delete  enum  

Allow Coach to delete agreed-to Client Agreements.

Accepted Values:
XNot granted
AGranted
try this...

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.

Parameters:

CoachID  int   (required)

ID of the Coach to be deleted.

try this...

Coach.getAll

Return values:

An array of zero or more items of the following form...
ID, int
firstName, string
lastName, string
email, string
dateAdded, date/time
isActive, boolean
homePhone, string
workPhone, string
cellPhone, string
isRegistered, boolean
address1, string
city, string
state, string
ZIP, string
avatarURL, string
loginCount, int
lastLoginDate, date/time or null
profile, an object of the following form...
businessName, string
biography, string
credentials, string
specialty, string
website, string
profileExtra, string
profileShow, boolean
profileShowEmail, boolean
profileShowHomePhone, boolean
profileShowWorkPhone, boolean
profileShowCellPhone, boolean
profileShowAddress, boolean

Description:

Get a listing of all Coaches

Parameters:

includeInactive  boolean   (defaults to false)

Set to true to include Coaches that are currently marked inactive.

sortOption  enum   (defaults to C)
Accepted Values:
CChronologically, newest first     // default value
AAlphabetical, active first
try this...

Coach.get

Return values:

ID, int
firstName, string
lastName, string
email, string
dateAdded, date/time
isActive, boolean
homePhone, string
workPhone, string
cellPhone, string
isRegistered, boolean
address1, string
city, string
state, string
ZIP, string
loginCount, int
lastLoginDate, date/time or null
profile, an object of the following form...
businessName, string
biography, string
credentials, string
specialty, string
website, string
profileExtra, string
profileShow, boolean
profileShowEmail, boolean
profileShowHomePhone, boolean
profileShowWorkPhone, boolean
profileShowCellPhone, boolean
profileShowAddress, boolean

Description:

Get basic information for a single Coach

Parameters:

CoachID  int   (required)

The ID of the Coach you wish to get.

try this...

Client

Client.add

Return values:

ClientID, int

Description:

Add a new client to your account

Parameters:

CoachID  int   (required)

The ID of the coach who is to be the new client's primary coach.

firstName  string   (required, maxlength 50)
lastName  string   (required, maxlength 50)
email  string   (required, maxlength 50)
homePhone  string   (maxlength 20)
cellPhone  string   (maxlength 20)
workPhone  string   (maxlength 20)
gender  enum   (defaults to U)
Accepted Values:
MMale
FFemale
UUnspecified     // default value
timezone  string  

The timezone of the new Client. If not provided, defaults to match her Coach's timezone.

address  string   (maxlength 100)

The client's street address.

city  string   (maxlength 100)

The client's city.

state  string   (maxlength 3)

The client's state.

ZIP  string   (maxlength 10)

The client's ZIP or postal code.

onDuplicateEmail  enum   (defaults to S)

What to do if a Client with the supplied email already exists.

Accepted Values:
SSkip and return existing ClientID     // default value
AAdd anyway, return new ClientID
EError out
upgradeIfNeeded  boolean   (defaults to true)

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.

sendInvite  boolean   (defaults to false)

Send true if the new client should be sent an invite email immediately.

inviteSubject  string  

Subject line of the invite email to be sent (if opted for). If not included, will use template setting.

inviteMessage  string  

Body of the invite email to be sent (if opted for), [magicLink] is required. If not included, will use template setting.

profileExtra  string   (maxlength 2000)

Any additional information you'd like to have on file, accessible at-a-glance.

try this...

Client.invite

Description:

Send Client an invitation email.

Parameters:

ClientID  int   (required)
inviteSubject  string  

Subject line of the invite email to be sent. If not included, will use template setting.

inviteMessage  string  

Body of the invite email to be sent, [magicLink] is required. If not included, will use template setting.

try this...

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:

ClientID  int   (required)
mayAccessWhenInactive  boolean   (defaults to false)

Setting true will grant continued, read-only access to the client.

try this...

Client.activate

Description:

Reactivate an inactive client.

Parameters:

ClientID  int   (required)
upgradeIfNeeded  boolean   (defaults to true)

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.

try this...

Client.update

Description:

Update basic information about a client

Parameters:

ClientID  int   (required)
firstName  string   (maxlength 50)
lastName  string   (maxlength 50)
homePhone  string   (maxlength 20)
cellPhone  string   (maxlength 20)
workPhone  string   (maxlength 20)
timezone  string  

The timezone of the Client.

address  string   (maxlength 100)

The client's street address.

city  string   (maxlength 100)

The client's city.

state  string   (maxlength 3)

The client's state.

ZIP  string   (maxlength 10)

The client's ZIP or postal code.

try this...

Client.setProfileExtra

Description:

Update a client's extra profile information.

Parameters:

ClientID  int   (required)
profileExtra  string   (maxlength 2000)

Any additional information you'd like to have on file, accessible at-a-glance.

try this...

Client.delete

Description:

Delete a Client. Cannot be undone, so call this with care!

Parameters:

ClientID  int   (required)
try this...

Client.getAll

Return values:

An array of zero or more items of the following form...
ID, int
CoachID, int
firstName, string
lastName, string
email, string
dateAdded, date/time
isActive, boolean
isFreebie, boolean
homePhone, string
workPhone, string
cellPhone, string
profileExtra, string
isRegistered, boolean
address1, string
city, string
state, string
ZIP, string
loginCount, int
lastLoginDate, date/time or null
CompanyID, int
companyName, string

Description:

Get a listing of all Clients

Parameters:

includeInactive  boolean   (defaults to false)

Set to true to include Clients that are currently marked inactive.

CoachID  int  

Get only Clients who are currently paired with a given Coach.

CompanyID  int  

Get only Clients who are belong to a given Company. Provide a zero to get clients that don't belong to any Company.

sortOption  enum   (defaults to C)
Accepted Values:
CChronologically, newest first     // default value
AAlphabetical, active first
try this...

Client.get

Return values:

ID, int
CoachID, int
firstName, string
lastName, string
email, string
dateAdded, date/time
isActive, boolean
isFreebie, boolean
homePhone, string
workPhone, string
cellPhone, string
profileExtra, string
isRegistered, boolean
address1, string
city, string
state, string
ZIP, string
loginCount, int
lastLoginDate, date/time or null
CompanyID, int
companyName, string

Description:

Get basic information for a single Client

Parameters:

ClientID  int   (required)

The ID of the Client you wish to get.

try this...

Pairing

Pairing.set

Description:

Create, update, or remove a Pairing between Coach and Client.

Parameters:

CoachID  int   (required)

ID of the Coach to be paired with a Client.

ClientID  int   (required)

ID of the Client to be paired with a Coach.

type  enum   (required)

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.

Accepted Values:
NNo access
RRead only access
CCoaching access     // default value
PCoaching as Primary Coach
try this...

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:

CoachID  int   (required)

ID of the Coach in the pairing to be deleted.

ClientID  int   (required)

ID of the Client in the pairing to be deleted.

try this...

Pairing.getForCoach

Return values:

An array of zero or more items of the following form...
ClientID, int
clientName, string
dateAdded, date/time
type, string

Description:

Get a listing of all Client Pairings with a given Coach

Parameters:

CoachID  int   (required)

ID of the Coach for whom pairings are to be gotten.

try this...

Pairing.getForClient

Return values:

An array of zero or more items of the following form...
CoachID, int
coachName, string
dateAdded, date/time
type, string

Description:

Get a listing of all Coach Pairings with a given Client

Parameters:

ClientID  int   (required)

ID of the Client for whom pairings are to be gotten.

try this...

Pairing.getHistory

Return values:

An array of zero or more items of the following form...
CoachID, int
ClientID, int
type, string
startDate, date/time
endDate, date/time

Description:

Get the history of Pairings between coaches and clients.

Parameters:

CoachID  int  

Filter the returned pairing history by coach.

ClientID  int  

Filter the returned pairing history by client.

startDateFrom  date/time  

Set to restrict Pairings returned to those starting at or after the provided value.

startDateTo  date/time  

Set to restrict Pairings returned to those starting at or before the provided value.

try this...

Action

Action.add

Return values:

ActionID, int
ActionProjectID, int

Description:

Add a new Action for a Client

Parameters:

ClientID  int   (required)

ID of the Client to whom this Action is to be assigned.

CoachID  int  

The ID of the Coach who is to be noted as assigning this action. Defaults to the Client's primary Coach.

theAction  string   (required)

A one-liner text of "what" the Action is.

dateDue  date   (required)

Date on which the Action is to be done.

timeDue  time   (required)

Time of day by which the Action is to be done.

timezoneOf  enum  

Who's timezone the due date is in. Defaults to that of the assigning Coach.

Accepted Values:
Ccoach
Lclient
Ause API setting
comment  string  

An optional additional comment about this Action.

sendNotification  boolean   (defaults to false)

Send true to notify the client via email of this new Action.

projectName  string  

Name of the Project for the new Action to be filed under. If left blank the new Action will be a standalone one.

ActionProjectID  int  

An alternative to projectName for specifying which project the new Action should be filed under.

weight  int  

Integer describing the relative significance of the Action within a project. Relevant only to Actions that are added to a project.

isLocked  boolean   (defaults to false)

Prevent the Client from modifying or deleting the Action.

reminderSet  string  

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.

Suggested Values:
L,E,1440
L,E,1440;L,E,120
L,T,60
L,E,1440;L,E,120;C,T,30
try this...

Action.getAll

Return values:

An array of zero or more items of the following form...
ID, int
ActionProjectID, int (zero for standalone Actions)
action, string
forWho, "C" for Coach or "L" for Client
dateDue, date/time
dateDone, date/time or null
isDone, boolean
isCanceled, boolean
reminderSet, an array of items of the following form...
ID, int
sendTo, "C" for Coach or "L" for Client
sendMethod, "E" for Email or "T" for Text
relativeMinutes, int
dateToSend, date/time
isSent, boolean
dateSent, date/time or null

Description:

Get the Actions for a given Client

Parameters:

ClientID  int   (required)
CoachID  int  

Filter a Client's Actions by which Coach assigned them.

ActionProjectID  int  

Filter the Actions you get back down to a given project.

includeDone  boolean   (defaults to false)

Set to true to include Actions that have already been marked complete.

includeCanceled  boolean   (defaults to false)

Set to true to include Actions that have been canceled.

includeForCoach  boolean   (defaults to false)

Set to true to include Actions that are for the coach to do.

try this...

Action.getReminders

Return values:

An array of zero or more items of the following form...
ID, int
sendTo, "C" for Coach or "L" for Client
sendMethod, "E" for Email or "T" for Text
relativeMinutes, int
dateToSend, date/time
isSent, boolean
dateSent, date/time or null

Description:

Get the reminders set for a given Action

Parameters:

ActionID  int   (required)
includeSent  boolean   (defaults to false)

Set to true to include Reminders that have already been sent (otherwise just return future reminders, i.e. those yet to be sent.

try this...

Action.setReminders

Description:

Set the reminders set for a given Action, overwriting whatever was set previously

Parameters:

ActionID  int   (required)
reminderSet  string  

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.

Suggested Values:
L,E,1440
L,E,1440;L,E,120
L,T,60
L,E,1440;L,E,120;C,T,30
try this...

Action.clearReminders

Description:

Delete all unsent reminders for a given Action

Parameters:

ActionID  int   (required)
try this...

Action.deleteReminder

Description:

Delete a particular Reminder for a given Action

Parameters:

ReminderID  int   (required)
try this...

Action.update

Description:

Update an Action. Any fields you provide will be used for the update, and any you omit will remain unchanged.

Parameters:

ActionID  int   (required)
theAction  string  
dateDue  date  
timeDue  time  
timezoneOf  enum  

Who's timezone the due date is in. Defaults to that of the assigning Coach.

Accepted Values:
Ccoach
Lclient
Ause API setting
projectName  string  

Name of the Project for the Aaction to be filed under. If set to "NULL" the Action will be changed to a standalone one.

ActionProjectID  int  

An alternative to projectName for specifying which project the Action should be filed under.

weight  int  

Integer describing the relative significance of the Action within a project. Relevant only to Actions that are in a project.

isLocked  boolean  

Prevent the Client from modifying or deleting the Action.

try this...

Action.delete

Description:

Delete an Action

Parameters:

ActionID  int   (required)
try this...

Action.markDone

Description:

Mark an Action complete

Parameters:

ActionID  int   (required)
dateDone  date  

Optionally specify when the Action was completed, otherwise defaults to the time of the call.

timeDone  time  

Optionally specify when the Action was completed, otherwise defaults to the time of the call.

timezoneOf  enum  

Who's timezone the date done is in. Defaults to that of the assigning Coach.

Accepted Values:
Ccoach
Lclient
Ause API setting
comment  string  

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).

try this...

Action.unmarkDone

Description:

Unmark an Action complete

Parameters:

ActionID  int   (required)
try this...

Action.cancel

Description:

Cancel an Action

Parameters:

ActionID  int   (required)
try this...

Action.uncancel

Description:

Undo the cancelation of a canceled Action

Parameters:

ActionID  int   (required)
try this...

Action.getAllProjects

Return values:

An array of zero or more items of the following form...
ID, int
name, string
description, string
totalWeight, int
dateAdded, date/time
dateModified, date/time or null

Description:

Fetch a listing of projects for a given Client

Parameters:

ClientID  int   (required)
try this...

Action.deleteProject

Description:

Delete an Action Project for a given Client

Parameters:

ClientID  int   (required)
ActionProjectID  int   (required)

The ID of the Project you wish to delete.

keepActions  boolean   (defaults to true)

Keep Actions within a Project around as standalone Actions. If false, delete any Actions within the Project.

try this...

Metric

Metric.add

Return values:

MetricID, int

Description:

Create a new Metric for a Client

Parameters:

ClientID  int   (required)

The ID of the Client who will be tracking this Metric.

name  string   (required)
units  string   (required)

The unit of measure for numbers to be reported, like "$", "lbs", or "minutes".

startDate  date   (required)

The date at which tracking is to be done.

endDate  date   (required)

The date through which tracking is to be done.

doTarget  boolean   (defaults to false)

Should a target apply for this Metric?

targetStart  number  

If a target, what should be the starting value?

targetEnd  number  

If a target, what should be the endgin value?

targetMode  enum   (defaults to H)

Dictates how the graph is to be colored regarding being over/under the target values, if set.

Accepted Values:
HHigher is better     // default value
LLower is better
dataMode  enum   (defaults to R)

Cumulative means that numbers as reported are to be added to a running total.

Accepted Values:
RRegular     // default value
CCumulative
repeatRule  enum   (defaults to weekdays)

On what frequency should values be reported for this Metric?

Accepted Values:
noneon an arbitrary basis
dailyevery day
bidailyevery other day
weekdaysevery weekday (Monday through Friday)     // default value
MWFevery Monday, Wednesday and Friday
TRevery Tuesday and Thursday
customWeeklyon select days of the week...
weeklyweekly
biweeklybiweekly
monthlyDOMmonthly by date of month
monthlyLastDOMmonthly on the last day of month
monthlyDOWmonthly by day of week
bimonthlyDOMbimonthly by date of month
bimonthlyDOWbimonthly by day of week
setReminders  boolean   (defaults to false)

Shall a regular reminder be set for this Metric?

reminderMode  enum  

On which basis should reminders be sent?

Accepted Values:
DODay Of, as in send on days when reporting should happen
DSDays Since, as in send X days since data was last reported
remindSendMethod  enum   (defaults to E)

How shall the recurring reminders be sent to your client for this Metric?

Accepted Values:
EEmail     // default value
TText
remindTime  time  

Time of day at which the reminder should be sent on called-for days.

remindDays  int  

Number of days since the last reporting that a reminder should be sent (applies only to the "DS" option for reminderMode).

try this...

Metric.getAll

Return values:

An array of zero or more items of the following form...
ID, int
name, string
units, string
totalWeight, int
startDate, date
endDate, date
targetMode, char ([H]igher or [L]lower)
targetStart, number
targetEnd, number
dataMode, char ([R]egular or [C]umulative)
repeatRule, string
dataSet, an array of items of the following form...
dateOf, date
value, number
comment, string

Description:

Get the Metrics for a given Client

Parameters:

ClientID  int   (required)

The Client whose Metrics are to be gotten.

includeCompleted  boolean   (defaults to false)

Set to true to include Metrics that have already been marked complete, otherwise complete Metrics will be omitted.

try this...

Metric.addData

Description:

Add a data point to a given Metric for a given day

Parameters:

MetricID  int   (required)

ID of the Metric to which data is to be added.

dateOf  date   (required)
value  number   (required)
comment  string  

Optional note about this data point.

try this...

Metric.clearDayData

Description:

Remove a Metric data point for a given day

Parameters:

MetricID  int   (required)

ID of the Metric to which data is to be cleared.

dateOf  date   (required)
try this...

Metric.update

Description:

Update a Metric. Any fields you provide will be used for the update, and any you omit will remain unchanged.

Parameters:

MetricID  int   (required)

ID of the Metric to be updated.

name  string  

New name for the Metric, if to be changed.

units  string  

The unit of measure for numbers to be reported, like "$", "lbs", or "minutes".

startDate  date  

The date at which tracking is to be done.

endDate  date  

The date through which tracking is to be done.

doTarget  boolean  

Should a target apply for this Metric?

targetStart  number  

If a target, what should be the starting value?

targetEnd  number  

If a target, what should be the endgin value?

targetMode  enum  

Dictates how the graph is to be colored regarding being over/under the target values, if set.

Accepted Values:
HHigher is better
LLower is better
dataMode  enum  

Cumulative means that numbers as reported are to be added to a running total.

Accepted Values:
RRegular
CCumulative
repeatRule  enum  

On what frequency should values be reported for this Metric?

Accepted Values:
noneon an arbitrary basis
dailyevery day
bidailyevery other day
weekdaysevery weekday (Monday through Friday)
MWFevery Monday, Wednesday and Friday
TRevery Tuesday and Thursday
customWeeklyon select days of the week...
weeklyweekly
biweeklybiweekly
monthlyDOMmonthly by date of month
monthlyLastDOMmonthly on the last day of month
monthlyDOWmonthly by day of week
bimonthlyDOMbimonthly by date of month
bimonthlyDOWbimonthly by day of week
setReminders  boolean  

Shall a regular reminder be set for this Metric?

reminderMode  enum  

On which basis should reminders be sent?

Accepted Values:
DODay Of, as in send on days when reporting should happen
DSDays Since, as in send X days since data was last reported
remindSendMethod  enum  

Send true to notify the client via email of this new Action.

Accepted Values:
EEmail
TText
remindTime  time  

Time of day at which the reminder should be sent on called-for days.

remindDays  int  

Number of days since the last reporting that a reminder should be sent (applies only to the "DS" option for reminderMode).

try this...

Metric.markComplete

Description:

Mark a Metric complete

Parameters:

MetricID  int   (required)

ID of the Metric to be marked complete.

try this...

Metric.unmarkComplete

Description:

Unmark a Metric complete

Parameters:

MetricID  int   (required)

ID of the Metric to be unmarked complete.

try this...

Metric.delete

Description:

Delete a Metric

Parameters:

MetricID  int   (required)

ID of the Metric to be deleted.

try this...

Appointment

Appointment.getTypes

Description:

Get the collection of Appointment Types available

Parameters:

CoachID  int   (required)

The ID of the Coach whom the Appointment Types are associated with.

try this...

Appointment.add

Description:

Add a new Appointment between Coach and Client

Parameters:

CoachID  int   (required)

The ID of the Coach whom the Appointment is with.

ClientID  int   (required)

The ID of the Client whom the Appointment is with.

AppointmentTypeID  int   (required)

The ID of the Appointment Type that the Appointment is to be of

alternateLabel  string   (maxlength 100)

Optional alternate label for the appointment (overrides the Appointment Type's name)

location  string   (maxlength 100)

Optional alternate location for the appointment (overrides the Appointment Type's location)

description  string   (maxlength 100)

Optional alternate description for the appointment (overrides the Appointment Type's description)

dateOf  date   (required)
timeOf  time   (required)
timezoneOf  enum  

Who's timezone the appointment date/time is in. Defaults to that of the Coach.

Accepted Values:
Ccoach
Lclient
Ause API setting
sendNotification  boolean   (defaults to false)

Send true if the Client should be sent a notification email immediately.

notificationSubject  string   (maxlength 200)

Subject line of the notification email to be sent (if opted for). If not included, will use template setting.

notificationMessage  string  

Body of the notification email to be sent (if opted for). If not included, will use template setting.

reminderSet  string  

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.

Suggested Values:
default
L,E,1440
L,E,1440;L,E,120
L,T,60
L,E,1440;L,E,120;C,T,30
try this...

Appointment.getAll

Return values:

An array of zero or more items of the following form...
ID, int
CoachID, int
ClientID, int
EngagementID, int, when belonging to an Engagement, otherwise zero
what, string
startDate, date/time
endDate, date/time
status, string, "A" for Active, "C" for Canceled, "P" for Pending request, "D" for Declined request
dateAdded, date/time
dateCanceled, date/time or null
location, string
description, string
reminderSet, an array of items of the following form...
ID, int
sendTo, "C" for Coach or "L" for Client
sendMethod, "E" for Email or "T" for Text
relativeMinutes, int
dateToSend, date/time
isSent, boolean
dateSent, date/time or null

Description:

Get Appointments for a given Coach/Client

Parameters:

CoachID  int  

Filter Appointments by Coach.

ClientID  int  

Filter Appointments by Client.

CompanyID  int  

Filter Appointments by the Company that the Clients belong to.

name  string  

Filter Appointments by name, supports partial matching on prefix.

dateFrom  date/time  

Set to restrict Appointments returned to those starting at or after the provided value.

dateTo  date/time  

Set to restrict Appointments returned to those starting at or before the provided value.

includePending  boolean   (defaults to false)

Set to true to include Appointments which are still just pending requests.

includeCanceled  boolean   (defaults to false)

Set to true to include Appointments that have been canceled.

try this...

Appointment.cancel

Description:

Cancel an Appointment

Parameters:

AppointmentID  int   (required)
notifyClient  boolean   (defaults to false)

Set to true to send a notification via email to the Client attendee of the Appointment.

comment  string  

Optional comment from the Coach to be sent as part of the cancelation email to the Client.

try this...

Appointment.delete

Description:

Delete an Appointment

Parameters:

AppointmentID  int   (required)
try this...

Session

Session.add

Return values:

SessionID, int

Description:

Add a new Session for a Client

Parameters:

ClientID  int   (required)
CoachID  int  

The ID of the Coach who is to be noted as writing this Session. Defaults to the Client's primary Coach.

title  string   (required, maxlength 200)
dateOf  date   (required)
timeOf  time   (required)
content  string   (required, maxlength 100000)
visibility  enum   (defaults to *)
Accepted Values:
*Visible to coach and client     // default value
CVisible to coaches only
PVisible to author only
try this...

Session.getAll

Return values:

An array of zero or more items of the following form...
ID, int
CoachID, int
ClientID, int
dateOf, date/time
title, text
content, text
isDraft, boolean
answerSet, an array of items of the following form...
name, string
value, string
numberValue, number

Description:

Get the Sessions for a given Client

Parameters:

ClientID  int  

Filter Sessions by Client.

CoachID  int  

Filter a Client's Sessions by which Coach wrote them.

dateFrom  date/time  

Set to restrict Sessions returned to those at or after the provided value.

dateTo  date/time  

Set to restrict Sessions returned to those at or before the provided value.

includeDrafts  boolean   (defaults to false)

Set to true to include Sessions not yet marked complete.

try this...

Session.update

Description:

Update a Session. Any fields you provide will be used for the update, and any you omit will remain unchanged.

Parameters:

SessionID  int   (required)
title  string   (maxlength 200)
dateOf  date  
timeOf  time  
content  string   (maxlength 100000)
visibility  enum   (defaults to *)
Accepted Values:
*Visible to coach and client     // default value
CVisible to coaches only
PVisible to author only
try this...

Session.delete

Description:

Delete a Session

Parameters:

SessionID  int   (required)
try this...

Worksheet

Worksheet.getAll

Return values:

An array of zero or more items of the following form...
ID, int
CoachID, int
ClientID, int
title, string
content, string
dateAssigned, date/time
dateDue, date/time
dateDone, date/time or null
isDone, boolean
answerSet, an array of items of the following form...
name, string
value, string
numberValue, number
reminderSet, an array of items of the following form...
ID, int
sendTo, "C" for Coach or "L" for Client
sendMethod, "E" for Email or "T" for Text
relativeMinutes, int
dateToSend, date/time
isSent, boolean
dateSent, date/time or null

Description:

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:

ClientID  int  

Filter Worksheets by Client.

CoachID  int  

Filter Client Worksheets by which Coach assigned them.

CompanyID  int  

Filter Client Worksheets by which Company they belong to.

title  string  

Filter a Client's Worksheets by which title, prefixed.

includeContent  boolean   (defaults to false)

Set to true to include the full HTML content of the Worksheet.

includeOutstanding  boolean   (defaults to false)

Set to true to include Worksheets not yet marked complete.

dateAssignedFrom  date  

Set to filter Worksheet by when they were assigned.

dateAssignedTo  date  

Set to filter Worksheet by when they were assigned.

try this...

Worksheet.getReminders

Return values:

An array of zero or more items of the following form...
ID, int
sendTo, "C" for Coach or "L" for Client
sendMethod, "E" for Email or "T" for Text
relativeMinutes, int
dateToSend, date/time
isSent, boolean
dateSent, date/time or null

Description:

Get the reminders set for a given Worksheet

Parameters:

WorksheetID  int   (required)
includeSent  boolean   (defaults to false)

Set to true to include Reminders that have already been sent (otherwise just return future reminders, i.e. those yet to be sent.

try this...

Worksheet.setReminders

Description:

Set the reminders set for a given Worksheet, overwriting whatever was set previously

Parameters:

WorksheetID  int   (required)
reminderSet  string  

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.

Suggested Values:
L,E,1440
L,E,1440;L,E,120
L,T,60
L,E,1440;L,E,120;C,T,30
try this...

Worksheet.clearReminders

Description:

Delete all unsent reminders for a given Worksheet

Parameters:

WorksheetID  int   (required)
try this...

Worksheet.deleteReminder

Description:

Delete a particular Reminder for a given Worksheet

Parameters:

ReminderID  int   (required)
try this...

Worksheet.delete

Description:

Delete a Worksheet

Parameters:

WorksheetID  int   (required)
try this...

Agreement

Agreement.getTemplates

Return values:

An array of zero or more items of the following form...
ID, int
title, text
content, text (if requested)

Description:

Get the Agreement Templates available for issuing to clients

Parameters:

title  string  

Filter Agreement Templates by which title, prefixed.

includeContent  boolean   (defaults to false)

Set to true to include the full HTML content of the Agreement Templates.

try this...

Agreement.issue

Return values:

AgreementID, int

Description:

Issue a new Agreement for a Client

Parameters:

ClientID  int   (required)
CoachID  int  

The ID of the Coach who is to be noted as issuing this Agreement. Defaults to the Client's primary Coach.

AgreementTemplateID  int   (required)

The ID of the Agreement Template to issue. Can be obtained from Agreement.getTemplates

title  string  

Allows you to specify an alternate title for the Agreement. When omitted, will default to that specified by the Agreement Template.

try this...

Agreement.getAll

Return values:

An array of zero or more items of the following form...
ID, int
ClientID, int
dateIssued, date/time
dateAgreed, date/time
title, text
content, text (if requested)

Description:

Get the Agreements on file for one or all Clients

Parameters:

ClientID  int  

Filter to Agreements belonging to a specific client.

title  string  

Filter Agreements by which title, prefixed.

includeContent  boolean   (defaults to false)

Set to true to include the full HTML content of the Agreements.

which  enum   (defaults to A)

Filter by Agreement status.

Accepted Values:
OOutstanding
AAgreed-to     // default value
BBoth Outstanding and Agreed-to
dateFrom  date  

Set to restrict Agreements returned to those issued at or after the provided value.

dateTo  date  

Set to restrict Agreements returned to those issued at or before the provided value.

try this...

Agreement.delete

Description:

Delete an Agreement

Parameters:

AgreementID  int   (required)
try this...

ClientFile

ClientFile.addAsUpload

Return values:

ClientFileID, int

Description:

Add a file shared with a Client

Parameters:

ClientID  int   (required)

The ID of the Client with whom to share this File.

CoachID  int  

The ID of the Coach who is to be noted as sharing this File. Defaults to the Client's primary Coach.

filename  string   (required, maxlength 300)
title  string   (maxlength 200)
folder  string   (maxlength 500)
description  string   (maxlength 1000)
fileData  string   (required, maxlength 5242880)

Data of the file to be uploaded, MUST BE Base64 encoded.

try this...

ClientFile.addAsURL

Return values:

ClientFileID, int

Description:

Add a file shared with a Client as an external URL

Parameters:

ClientID  int   (required)

The ID of the Client with whom to share this File.

CoachID  int  

The ID of the Coach who is to be noted as sharing this File. Defaults to the Client's primary Coach.

URL  string   (required, maxlength 300)

The URL of the link to share

title  string   (maxlength 200)
folder  string   (maxlength 500)
description  string   (maxlength 1000)
try this...

Invoice

Invoice.add

Return values:

InvoiceID, int

Description:

Add a new Invoice for a Client

Parameters:

ClientID  int   (required)

The ID of the Client for whom this invoice is.

dateOf  date   (required)
dateDue  date  

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.

number  string   (maxlength 20)

If not supplied, a logical next invoice number will be assigned. Letters are allowed, e.g. "A1002".

taxRate  number  

A percentage-based rate of tax to be applied, e.g. 7.5 means apply a 7.5% tax.

onDuplicateNumber  enum   (defaults to S)

What to do if an Invoice with the supplied number already exists.

Accepted Values:
SSkip and return existing InvoiceID     // default value
AAdd anyway, return new InvoiceID
EError out
currency  string   (maxlength 3)

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.

lineItemSet  string  

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"

Suggested Values:
One month of coaching::400
One month of coaching::400
Being a Baller 6-week Course::600
collectPaymentIfPossible  boolean   (defaults to false)

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.

try this...

Invoice.send

Description:

Send a Client their Invoice via email.

Parameters:

InvoiceID  int   (required)

The ID of the Invoice to be sent. Invoice Number also accepted when prefixed with a "#", e.g. "#1005".

sendTo  enum   (defaults to L)

If not supplied, will send to the client. By supplying a valid email address this call can send to any 3rd party.

Accepted Values:
LThe Client     // default value
CThe Client's primary Coach
someone@example.comAn arbitrary email of a 3rd party
message  string  

An optional message to include as part of the invoice.

Suggested Values:
Thanks for your business!
Please pay within the next 7 days.
try this...

Invoice.getAll

Return values:

An array of zero or more items of the following form...
ID, int
invoiceNumber, string
dateOf, date
dateDue, date
currency, string
amount, number
amountPaid, number
taxRate, number
ClientID, int
firstName, string
lastName, string
email, string
lineItemSet, an array of items of the following form...
item, string
amount, number
paymentSet, an array of items of the following form...
datePaid, date/time
amount, number
method, string
checkNumber, string

Description:

Get the Invoices for a given Client

Parameters:

ClientID  int  

Filter invoices by client. If omitted, invoices for all Clients are returned.

CoachID  int  

Filter a Client's Invoices by a client's primary Coach.

dateFrom  date/time  

Set to restrict Invoices returned to those at or after the provided value.

dateTo  date/time  

Set to restrict Invoices returned to those at or before the provided value.

try this...

Invoice.get

Return values:

ID, int
invoiceNumber, string
dateOf, date
dateDue, date
currency, string
amount, number
amountPaid, number
taxRate, number
ClientID, int
firstName, string
lastName, string
email, string
lineItemSet, an array of items of the following form...
item, string
amount, number
paymentSet, an array of items of the following form...
datePaid, date/time
amount, number
method, string
checkNumber, string

Description:

Get a given Invoice

Parameters:

InvoiceID  int  

The ID of the Invoice to be updated. Invoice Number also accepted when prefixed with a "#", e.g. "#1005".

try this...

Invoice.update

Description:

Update an Invoice. Any fields you provide will be used for the update, and any you omit will remain unchanged.

Parameters:

InvoiceID  int   (required)

The ID of the Invoice to be updated. Invoice Number also accepted when prefixed with a "#", e.g. "#1005".

dateOf  date  

A new date of the Invoice, if it is to be changed.

number  string   (maxlength 20)

A new number for the Invoice, if it is to be changed.

taxRate  number  

A percentage-based rate of tax to be applied, e.g. 7.5 means apply a 7.5% tax.

lineItemSet  string  

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"

Suggested Values:
One month of coaching::400
One month of coaching::400
Being a Baller 6-week Course::600
try this...

Invoice.delete

Description:

Delete an Invoice

Parameters:

InvoiceID  int   (required)

The ID of the Invoice to be deleted. Invoice Number also accepted when prefixed with a "#", e.g. "#1005".

try this...

Invoice.getPayments

Return values:

An array of zero or more items of the following form...
ID, int
InvoiceID, int
invoiceNumber, string
datePaid, date
amount, number
currency, string
method, string
checkNumber, string

Description:

Get Invoice Payments

Parameters:

dateFrom  date/time  

Set to restrict Invoice Payments returned to those at or after the provided value.

dateTo  date/time  

Set to restrict Invoice Payments returned to those at or before the provided value.

try this...

Invoice.addPayment

Return values:

PaymentID, int

Description:

Record a Payment on a given Invoice

Parameters:

InvoiceID  int   (required)

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".

dateOf  date/time  

Will fill in as the current time when not supplied. Future dates not allowed.

amount  number   (required)
method  enum   (defaults to Credit Card)

If not supplied, will assume "Credit Card"

Accepted Values:
CashCash
CheckCheck
Credit CardCredit Card     // default value
Bank TransferBank Transfer
OtherOther
checkNumber  string   (maxlength 20)

Optional memo that will be saved when supplied and method="Check"

allowOverpay  boolean   (defaults to false)

If not set to "true", will throw an error if the added payment results in a net overpay of the invoice.

try this...

Invoice.deletePayment

Description:

Delete a Payment on a given Invoice

Parameters:

PaymentID  int   (required)

The ID of the Invoice Payment which is to be deleted.

try this...

Engagement

Engagement.getTemplates

Return values:

An array of zero or more items of the following form...
ID, int
name, text
managingCoachID, int
duration, int
allocationUnit, string
allocation, int

Description:

Get the Engagement Templates available.

Parameters:

try this...

Engagement.addForClient

Return values:

EngagementID, int

Description:

Add a new Engagement for a Client.

Parameters:

ClientID  int   (required)

The ID of the Client for whom the Engagement is to be added.

EngagementTemplateID  int   (required)

The ID of the Engagement Template to be used to fill in the details of the new Engagement.

managingCoachID  int  

The ID of the Coach who is to be noted as managing the Engagement. Defaults to the managing coach specified by the Engagement Template.

startDate  date  

The date that the Engagement is to begin. Defaults to today if not provided.

endDate  date  

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.

allocation  string  

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.

Suggested Values:
12 A
6 H
initializeInvoices  boolean   (defaults to false)

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.

allowMultipleCurrentEngagements  boolean   (defaults to false)

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.

try this...

Engagement.update

Description:

Update an Engagement. Any fields you provide will be used for the update, and any you omit will remain unchanged.

Parameters:

EngagementID  int   (required)
managingCoachID  int  

The ID of the Coach who is to be noted as managing the Engagement.

name  string  
startDate  date  
endDate  date  

If provided but set to an empty or otherwise invalid date, the Engagement will be set to continue indefinitely.

allocation  string  

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").

Suggested Values:
12 A
6 H
try this...

Engagement.complete

Description:

Delete an Engagement

Parameters:

EngagementID  int   (required)
whenOption  enum   (defaults to N)

When should the Engagement be noted as having been completed?

Accepted Values:
EAs of the Engagement's end date
UAs of the Engagement's last Appointment
NNow     // default value
try this...

Engagement.cancel

Description:

Delete an Engagement

Parameters:

EngagementID  int   (required)
try this...

Engagement.reopen

Description:

Re-open a canceled or completed Engagement

Parameters:

EngagementID  int   (required)
try this...

Engagement.delete

Description:

Delete an Engagement

Parameters:

EngagementID  int   (required)
try this...

Engagement.getAll

Return values:

An array of zero or more items of the following form...
ID, int
type, string
ClientID, int
CompanyID, int
CoachID, int
withName, string
name, string
startDate, date
endDate, date
allocationUnits, string
allocation, int
allocationUsedP, int
allocationUsedA, int
allocationUsedV, int
allocationPerClient, int
nextInvoiceDate, date
isComplete, boolean
isCanceled, boolean
dateClosed, date/time
dateAdded, date/time
AppointmentSet, an array of items of the following form...
ID, int
CoachID, int
ClientID, int
what, string
startDate, date/time
endDate, date/time
status, string
dateAdded, date/time
dateCanceled, date/time or null
countsInEngagement, int

Description:

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:

ClientID  int  

Filter Engagements by Client.

CompanyID  int  

Filter Engagements by Company.

CoachID  int  

Filter Engagements by the managing Coach.

startDateFrom  date/time  

Set to restrict Engagements returned to those with a start date at or after the provided value.

startDateTo  date/time  

Set to restrict Engagements returned to those with a start date at or before the provided value.

endDateFrom  date/time  

Set to restrict Engagements returned to those with an end date at or after the provided value.

endDateTo  date/time  

Set to restrict Engagements returned to those with an end date at or before the provided value.

includeAppointments  boolean   (defaults to false)

Set to true to include Appointments which count towards the Engagement.

try this...

Offering

Offering.getAll

Return values:

An array of zero or more items of the following form...
ID, int
CoachID, int
name, string
price, number
blurb, string
description, string
notifyEmail, string
URL, string
iframeURL, string
scriptURL, string

Description:

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, int
name, string
URL, string
iframeURL, string
scriptURL, string
OfferingSet, an array of items of the following form...
ID, int
CoachID, int
name, string
price, number
blurb, string
description, string

Description:

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, int
CoachID, int
name, string
dayDuration, int
itemTimeOption, string

Description:

Get the Courses available for Clients to be added to.

Parameters:

CoachID  int  

Filter Courses by the owning Coach.

try this...

Course.addClientParticipant

Return values:

CourseParticipantID, int

Description:

Add a Client as a participant in a Course

Parameters:

ClientID  int   (required)

The ID of the Client to be added.

CoachID  int  

The ID of the Coach who is effectively assigning/running this Course Participation. If omitted, defaults to the Primary Coach of the provided ClientID.

CourseID  int   (required)

The ID of the Course to which the Client is to be added.

startDate  date  

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.

startOnDay  int  

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].

dispatchEarlierStartDayItems  boolean   (defaults to true)

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?).

try this...

Course.pauseParticipant

Description:

Pause a participation along the timeline of its respective Course

Parameters:

CourseParticipantID  int   (required)

The ID of the Participant to be paused.

unpauseDate  date  

Date at which the Participant is to resume the Course. Omit to pause indefinitely.

try this...

Course.unpauseParticipant

Description:

Resume a participation along the timeline of its respective Course

Parameters:

CourseParticipantID  int   (required)

The ID of the Participant to be unpaused.

try this...

Course.fastForwardParticipant

Description:

Fast forward a participation along the timeline of its respective Course

Parameters:

CourseParticipantID  int   (required)

The ID of the Participant to be fast forwarded.

days  int  

How many days to fast forward? Must be 1 or greater.

dispatchItems  boolean   (defaults to false)

Should Course items during the fast-forward period be dispatched to this participant?

issueNotifications  boolean   (defaults to false)

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.

try this...

Course.rewindParticipant

Description:

Rewind a participation along the timeline of its respective Course

Parameters:

CourseParticipantID  int   (required)

The ID of the Participant to be rewound.

days  int  

How many days to rewind? Must be 1 or greater.

deleteItems  boolean   (defaults to false)

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?

try this...

Course.stopParticipant

Description:

Remove a participation from its respective Course

Parameters:

CourseParticipantID  int   (required)

The ID of the Participant to be removed.

deleteItems  boolean   (defaults to false)

Should already-dispatched Course Items be deleted as well?

try this...

Course.getAllClientParticipants

Return values:

An array of zero or more items of the following form...
ID, int
ClientID, int
clientFirstName, string
clientLastName, string
startDate, date
dayOf, int
isPaused, boolean
unpauseDate, date
isComplete, boolean
dateCompleted, date

Description:

Get the Participants for a given Course

Parameters:

CourseID  int   (required)

The ID of the Course whose Participants are to be gotten.

ClientID  int  

Optionally filter by ID of the Client for whom Participations are to be gotten.

includeCompleted  boolean  

Include Participants whose Course timeline progression has already been completed.

try this...

Course.getAllGroupParticipants

Return values:

An array of zero or more items of the following form...
ID, int
groupName, string
includedMembers, an array of items of the following form...
ClientID, int
clientName, string
startDate, date
dayOf, int
isPaused, boolean
unpauseDate, date
isComplete, boolean
dateCompleted, date

Description:

Get the Group Participants for a given Course

Parameters:

CourseID  int   (required)

The ID of the Course whose Participants are to be gotten.

GroupID  int  

Optionally filter by ID of the Group for whom Participations are to be gotten.

includeCompleted  boolean  

Include Participants whose Course timeline progression has already been completed.

try this...

Course.addClientAvailability

Return values:

CourseAvailabilityID, int

Description:

Add Availability of a Course to a Client

Parameters:

ClientID  int   (required)

The ID of the Client to make the Course availabile to.

CoachID  int  

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.

CourseID  int   (required)

The ID of the Course that the Client is to have made available.

dateAvailable  date  

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.

try this...

Course.getAvailabilitiesForClient

Return values:

An array of zero or more items of the following form...
ID, int
ClientID, int
CourseID, int
clientFirstName, string
clientLastName, string
courseName, string
dateAdded, date
dateAvailable, date
isUsed, boolean
dateUsed, date

Description:

Get the Courses Available to a given Client

Parameters:

ClientID  int   (required)

ID of the Client for whom Course Availabilities are to be gotten.

includeUsed  boolean  

Include Course Availabilities which have already been used.

try this...

Course.getAvailabilitiesForCourse

Return values:

An array of zero or more items of the following form...
ID, int
ClientID, int
CourseID, int
clientFirstName, string
clientLastName, string
courseName, string
dateAdded, date
dateAvailable, date
isUsed, boolean
dateUsed, date

Description:

Get the Participants for a given Course

Parameters:

CourseID  int   (required)

The ID of the Course for which Client Availabilities are to be gotten.

includeUsed  boolean  

Include Course Availabilities which have already been used.

try this...

Course.removeClientAvailability

Description:

Make a Course no longer available to a client

Parameters:

CourseAvailabilityID  int   (required)

The ID of the Course Availability to be removed.

try this...

Group

Group.getAll

Return values:

An array of zero or more items of the following form...
ID, int
CoachID, int
name, string
type, string

Description:

Get the Groups available for Clients to be added to.

Parameters:

CoachID  int  

Filter Groups by the owning Coach.

try this...

Group.addClientMember

Return values:

GroupClientID, int

Description:

Add a Client as a member in a Group

Parameters:

ClientID  int   (required)

The ID of the Client to be added.

GroupID  int   (required)

The ID of the Course to which the Client is to be added.

try this...

Group.getAllClientMembers

Return values:

An array of zero or more items of the following form...
ID, int
ClientID, int
clientFirstName, string
clientLastName, string
startDate, dateAdded
isActive, boolean

Description:

Get the Client Members for a given Group

Parameters:

GroupID  int   (required)

The ID of the Group whose Client Members are to be gotten.

includeInactive  boolean  

Include Group Clients who are inactive.

try this...

Group.deactivateClientMember

Description:

Deactivate an existing Client Member's participation within a Group.

Parameters:

GroupClientID  int   (required)
try this...

Group.activateClientMember

Description:

Reactivate an inactive Client Member's participation within a Group.

Parameters:

GroupClientID  int   (required)
try this...

Group.removeClientMember

Description:

Remove a Client from a Group

Parameters:

GroupClientID  int   (required)

The ID of the Group Client Member to be removed.

try this...

Group.getAllCoachMembers

Return values:

An array of zero or more items of the following form...
ID, int
CoachID, int
coachFirstName, string
coachLastName, string
isOwner, boolean
startDate, dateAdded
isActive, boolean

Description:

Get the Coach Members for a given Group

Parameters:

GroupID  int   (required)

The ID of the Group whose Coach Members are to be gotten.

includeInactive  boolean  

Include Group Coaches who are inactive.

try this...

Company

Company.getAll

Return values:

An array of zero or more items of the following form...
ID, int
name, string
dateAdded, date/time
isActive, boolean
address1, string
city, string
state, string
ZIP, string
country, string

Description:

Get a listing of all Companies

Parameters:

includeInactive  boolean   (defaults to false)

Set to true to include Companies that are marked inactive.

sortOption  enum   (defaults to C)
Accepted Values:
CChronologically, newest first     // default value
AAlphabetical, active first
try this...

Personnel

Personnel.getAll

Return values:

An array of zero or more items of the following form...
ID, int
firstName, string
lastName, string
email, string
dateAdded, date/time
isActive, boolean
homePhone, string
workPhone, string
cellPhone, string
profileExtra, string
isRegistered, boolean
address1, string
city, string
state, string
ZIP, string
loginCount, int
lastLoginDate, date/time or null
CompanyID, int
companyName, string

Description:

Get a listing of all Personnel

Parameters:

includeInactive  boolean   (defaults to false)

Set to true to include Personnel that are marked inactive.

CompanyID  int  

Get only Personnel who are with a given Company.

sortOption  enum   (defaults to C)
Accepted Values:
CChronologically, newest first     // default value
AAlphabetical, active first
try this...

ClientData

ClientData.getByField

Return values:

data, CSV

Description:

Get a CSV-formatted spreadsheet of client data for a given field name

Parameters:

fieldname  string   (required)

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.

CoachID  int  

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.

ClientID  int  

The ID of the client for whom data is to be returned, if desired only for a single, specific client.

dateFrom  date  

Set to restrict data returned to those dated at or after the provided value.

dateTo  date  

Set to restrict data returned to those dated at or before the provided value.

includeInactive  boolean   (defaults to false)

Include data for Clients who are inactive.

includeCoach  boolean   (defaults to false)

Set true to inclue the name of the Primary Coach for output Client records.

dateBucket  enum   (defaults to W)

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.

Accepted Values:
DDays
WWeeks     // default value
MMonths
whatData  enum   (defaults to N)

Data points often have a sensible textual and numeric value. Set this to get one, the other, or both.

Accepted Values:
NNumeric values     // default value
TText values
BBoth text and numeric values
structure  enum   (defaults to D)

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.

Accepted Values:
DDate Grid     // default value
LData Point Listing
try this...

ClientData.getActivityStats

Return values:

data, CSV

Description:

Get a CSV-formatted spreadsheet of client activity stats for a given date range.

Parameters:

CoachID  int  

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.

ClientID  int  

The ID of the client for whom data is to be returned, if desired only for a single, specific client.

GroupID  int  

The ID of the Group for whose client members data is to be returned.

CompanyID  int  

The ID of the Company for whose client members data is to be returned.

EngagementID  int  

The ID of the Engagement for whose client data is to be returned.

dateBucket  enum   (defaults to W)

Group activity statistics according to your bucket size of choice.

Accepted Values:
DDays
WWeeks     // default value
MMonths
QQuarters
YYears
dateFrom  date  

The lower bound of the date range to report stats on..

dateTo  date  

The upper bound of the date range to report stats on.

itemTypes  string  

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.

includeInactive  boolean   (defaults to false)

Include data for Clients who are inactive.

includeTotals  boolean   (defaults to true)

Set true to inclue a totals column.

includeAverages  boolean   (defaults to true)

Set true to inclue an averages column.

try this...

Account

Account.me

Return values:

firstName, string
lasName, string
email, string
username, string

Description:

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:

  1. Getting an error code back in this manner means the HTTP request itself was successful (i.e. HTTP 200 status code on the request).
  2. For successful calls, the error field of the returned JSON object will ALWAYS be present and ALWAYS have the value 0.
  3. Non-zero values are sufficient to indicate that the there as an API-level error with the call, and no action was performed.
  4. When an error is present, the message field of the returned JSON object will be set with a message about the error.
  5. Please note that the 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.

1XX:  Failures of authentication and permissions
101Missing API ID
102Missing API Key
103Invalid API ID
104Invalid API Key
105Account is not active
106API not enabled
2XX:  Situations in which there's a problem with the function call
201The "a" parameter (which indicates which function to call) is missing
202The "a" parameter is invalid, i.e. specifies a function which does not exist
3XX:  Situations in which there's an invalid parameter passed to a function call
301A required value was not supplied
302An invalid entity ID was provided (like a non-existent ActionID or ClientID)
303An invalid email was supplied
304An invalid date was supplied
305An invalid time was supplied
306An invalid name was supplied
311An unknown CoachID was supplied
312The CoachID supplied references an inactive Coach
313The CoachID supplied references an non-coaching Coach
321A non-valid reminderSet value supplied (commma-separated triplet expected)
322A non-valid parameter for a reminder was supplied
4XX:  Situations in which conditions are such that the function call cannot be made
401The Client already exists with the same email and so cannot be added
402The [magicLink] tag was missing from the inviteMessage for the Client invitation
403The Client invitation cannot be sent because the client has already registered
404An attempt to add a Client, but no space to do so (and you haven't given permission to upgrade)
405An attempt to update Client who owns their own account details
411The Coach already exists with the same email and so cannot be added
412The [magicLink] tag was missing from the inviteMessage for the Coach invitation
413The Coach invitation cannot be sent because the Coach has already registered
414The Coach who owns the account cannot be deleted or deactivated
415A coach who is still the Primary Coach for one or more Clients cannot be deleted or deactivated
416The account owner cannot have permissions set via the API
420The Action cannot be canceled for it was previously marked complete
421The Action cannot be marked complete for it was previously canceled
430The Metric is part of a Group or Coures and thus not fully editable
431The Metric data is for an invalid date and thus cannot be added
440The Client already has an Engagement that overlaps with this one
441The Engagement cannot be marked complete for it is already canceled.
442The Engagement cannot be canceled for it is already marked complete.
443Invalid or missing value for Engagement allocation.
470The provided fileData is too large
471The provided fileData will not fit within the storage limits of the account
472The provided URL is not valid
481The Client is already an active participant in the Course
482The Client cannot have the Coach be the assigning party for the Course
483The Course Participation is already paused or unpaused
491The Invoice already exists with the same number and so cannot be added
492The Invoice cannot be created without specifying one or more line items
493A non-valid lineItemSet value was supplied (newline-separated line items expected)
494A non-valid parameter for a line item was supplied ([label]::[amount] is the expected format)
495A non-valid sendTo value was supplied (should be a valid email if not L or C)
496A non-valid amount was supplied (should be above zero and probably not exceed the balance)
497A non-valid dateOf was supplied (cannot be in the future)
498The 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 == '' '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($chCURLOPT_URL$APIURL);
    
curl_setopt($chCURLOPT_RETURNTRANSFERtrue);
    
curl_setopt($chCURLOPT_POST1);
    
curl_setopt($chCURLOPT_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($rawResulttrue);
        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.