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 Client Client.add Client.invite Client.deactivate Client.activate Client.update Client.setProfileExtra Client.delete Client.getAll 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 Session Session.add Session.getAll Session.update Session.delete Worksheet Worksheet.getAll Worksheet.getReminders Worksheet.setReminders Worksheet.clearReminders Worksheet.deleteReminder Worksheet.delete Invoice Invoice.add Invoice.send Invoice.getAll Invoice.update Invoice.delete Invoice.addPayment Invoice.deletePayment Course Course.getAll Course.addClientParticipant Course.pauseParticipant Course.unpauseParticipant Course.fastForwardParticipant Course.rewindParticipant Course.stopParticipant Course.getAllClientParticipants Group Group.getAll Group.addClientMember Group.getAllClientMembers Group.deactivateClientMember Group.activateClientMember Group.removeClientMember 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, leave a message in the lower-right corner of the screen (or if I'm online, chat me).

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 occured 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 preseme 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  
Accepted Values:
MMale
FFemale
UUnknown     // default value
timezone  string  

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

onDuplicateEmail  enum  

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  

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  

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

profileShowHomePhone  boolean  

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

profileShowWorkPhone  boolean  

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

profileShowCellPhone  boolean  

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

profileShowEmail  boolean  

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

profileShowAddress  boolean  

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.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
Templates.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
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, 2012-03-27 8:09pm
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 a listing of all Coaches

Parameters:

includeInactive  boolean  

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

sortOption  enum  
Accepted Values:
CChronologically, newest first     // default value
AAlphabetical, active first
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  
Accepted Values:
MMale
FFemale
UUnknown     // 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  

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  

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  

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.

clientTerms  string  

Terms for the new client to agree to upon registering her account. HTML allowed. 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.

Parameters:

ClientID  int   (required)
try this...

Client.activate

Description:

Reactivate an inactive client.

Parameters:

ClientID  int   (required)
upgradeIfNeeded  boolean  

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

Description:

Get a listing of all Clients

Parameters:

includeInactive  boolean  

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

CoachID  int  

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

sortOption  enum  
Accepted Values:
CChronologically, newest first     // default value
AAlphabetical, active first
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...
type, string
startDate, date/time
endDate, date/time

Description:

Get a listing of the history of Pairings between a given Coach/Client pair.

Parameters:

CoachID  int  

ID of the Coach for which the pairing history is to be gotten.

ClientID  int  

ID of the Client for which the pairing history is to be gotten.

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  

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  

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

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

includeCanceled  boolean  

Set to true to include Actions that have been canceled.

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  

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 due date is in. Defaults to that of the assigning Coach.

Accepted Values:
Ccoach
Lclient
Ause API setting
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  

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  

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     // default value
LLower is better
dataMode  enum  

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

Accepted Values:
RRegular     // default value
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)     // default value
MWFevery Monday, Wednesday and Friday
TRevery Tuesday and Thursday
weeklyweekly
biweeklybiweekly
monthlyDOMmonthly by date 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  

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  

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
weeklyweekly
biweeklybiweekly
monthlyDOMmonthly by date 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  

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
what, string
startDate, date/time
endDate, date/time
status, string
dateAdded, date/time
dateCanceled, date/time or null
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.

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  

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

includeCanceled  boolean  

Set to true to include Appointments that have been canceled.

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  
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
dateOf, date/time
title, text
content, text

Description:

Get the Sessions for a given Client

Parameters:

ClientID  int   (required)
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.

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

Parameters:

ClientID  int   (required)
CoachID  int  

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

title  string  

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

includeContent  boolean  

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

includeOutstanding  boolean  

Set to true to include Worksheets that not yet completed.

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  

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

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

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

Description:

Send a Client their Invoice via email.

Parameters:

InvoiceID  int   (required)

The ID of the Invoice to be sent.

sendTo  enum  

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
dateOf, date
number, text
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.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.

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.

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.

dateOf  date/time  

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

amount  number   (required)
method  enum  

If not supplied, will assume "Credit Card"

Accepted Values:
0Cash     // default value
1Check
2Credit Card
3Bank Transfer
checkNumber  string   (maxlength 20)

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

allowOverpay  boolean  

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

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  

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  

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

issueNotifications  boolean  

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  

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  

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
clientName, string
startDate, date
dayOf, int
isPaused, boolean
unpauseDate, date
isComplete, boolean

Description:

Get the Participants for a given Course

Parameters:

CourseID  int   (required)

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

includeCompleted  boolean  

Include Participants whose Course timeline progression has already been completed.

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
clientName, 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:

GroupMemberID  int   (required)

The ID of the Client Member to be removed.

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

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", array(
        
'ClientID'   => $ClientID,
        
'theAction'  => 'Test the API',
        
'dateDue'    => '4/5/2017'// 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 />Good times, y'all.";
}
    

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

I 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!