Introduction

The AdvicePay API is organized around REST. Our API has predictable resource-oriented URLs, accepts and returns JSON-encoded responses, and uses standard HTTP response codes and verbs.

You can use the API through our test environment, which does not affect your live data or interact with banking networks.

For testing, the base URL is https://demo.advicepay.com. For live requests, https://app.advicepay.com is the base URL.

Authorization

curl "api_endpoint_here"
  -H "Authorization: Bearer advicepay_api_token_or_access_token_here"

import "net/http"

req, _ := http.NewRequest("GET", "api_endpoint_here", nil)
req.Header.Add("Authorization", "Bearer advicepay_api_token_or_access_token")
resp, _ := http.DefaultClient.Do(req)

AdvicePay uses private API keys to allow access to the API. AdvicePay expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer advicepay_api_token_or_access_token

There are 2 methods of authorization available: API token (Deprecated) and OAuth 2.0.

OAuth 2.0 Authorization Code

The Authorization Code flow is useful for user-level integrations where AdvicePay users are within different accounts. OAuth clients for firms with developer access can be added within the developer console. OAuth clients for our integration partners are added upon request. You will need to provide your company name, website URL, logo, and redirect URI. A client ID and secret will be securely provisioned. The flow to authorize users for your app is:

Users are redirected to AdvicePay by your site and prompted to authorize your app
Users are redirected back to your site by AdvicePay
Your site requests an access token and refresh token using an authorization code
Your site refreshes the access token and the refresh token using a refresh token
Your site makes API calls using the access token

1. Requesting authorization from the user

curl /oauth2/authorize?client_id=yourClientID&redirect_uri=https%3A%2F%2Fwww.example.com%2Foauth&scope=all&state=xj15na

import "net/http"

// Build request
req, err := http.NewRequest("GET", "/oauth2/authorize?client_id=yourClientID&redirect_uri=https%3A%2F%2Fwww.example.com%2Foauth&scope=all&state=xj15na", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

HTTP Request

GET /oauth2/authorize

Query Parameters

Parameter	Description
client_id	Your provisioned client ID
redirect_uri	The URL in your application where users will be sent after authorization (must match what is provided when initially getting your OAuth client provisioned)
scope	Currently, only `all` is supported
state (optional)	An arbitrary string used to protect against cross-site request forgery attacks

2. Users are redirected back to your site by AdvicePay

If the user accepts your request, AdvicePay redirects back to your site with a temporary code as a query parameter as well as the state you provided in the previous step. The temporary code will expire after 10 minutes. If the states don't match, then a third party created the request, and you should abort the process.

For example, if your redirect URI is http://localhost/example and you provided the state xj15na in the previous step, your application would receive a GET request at the following URL upon upon authorization:

http://localhost/example?code=3fbbcd39-cd9c&state=xj15na

If the user rejects access, your application would receive a GET request at the following URL:

http://localhost/example?error=access_denied&state=xj15na

3. Requesting an access token and refresh token using your authorization code

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=authorization_code&code=362ad374-735c-4f69-aa8e-bf384f8602de&redirect_uri=http://example.com/oauth&client_id=yourClientID&client_secret=yourClientSecret" /oauth2/access_token

import "net/http"

// Build request
req, err := http.NewRequest("POST", "/oauth2/access_token", "grant_type=authorization_code&code=362ad374-735c-4f69-aa8e-bf384f8602de&redirect_uri=http://example.com/oauth&client_id=yourClientID&client_secret=yourClientSecret")
req.Header.Add("Content-Type", "application/x-www-form-urlencoded")
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "access_token": "228c9f52-c003", 
  "access_token_expires_at": 1606942087, 
  "refresh_token": "dsfslBBDFSFS343", 
  "refresh_token_expires_at": 1609534087, 
  "scope": scope, 
  "token_type": "bearer"
}

HTTP Request

POST /oauth2/access_token

Form Fields

Parameter	Description
client_id	Your provisioned client ID
client_secret	Your provisioned client secret (required when authentication method is Client Secret POST)
client_assertion_type	The assertion type for authentication (required when authentication method is Client Secret JWT or Private Key JWT)
client_assertion	The JWT assertion for authentication (required when authentication method is Client Secret JWT or Private Key JWT)
code	The authorization code you received at the redirect URI in the previous step
grant_type	The OAuth 2.0 grant type ("authorization_code" should be used when using an authorization code to retrieve the access token)
redirect_uri	The URL in your application where users will be sent after authorization. It is used here to verify your OAuth client credentials.
state (optional)	The arbitrary string you provided in step 1

You will get a JSON response containing an access token and refresh token for the user. These tokens should be stored securely and not be exposed outside of making API calls to AdvicePay. Access tokens expire after 5 minutes. Refresh tokens are single-use and expire after 30 days.

4. Refreshing the access token and refresh token using your refresh token

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=refresh_token&refresh_token=dsfslBBDFSFS343&client_id=yourClientID&client_secret=yourClientSecret" /oauth2/access_token

import "net/http"

// Build request
req, err := http.NewRequest("POST", "/oauth2/access_token", "grant_type=refresh_token&refresh_token=dsfslBBDFSFS343&client_id=yourClientID&client_secret=yourClientSecret")
req.Header.Add("Content-Type", "application/x-www-form-urlencoded")
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "access_token": "228c9f52-c003", 
  "access_token_expires_at": 1606942087, 
  "refresh_token": "babadfdff55343434", 
  "refresh_token_expires_at": 1609534087, 
  "scope": scope, 
  "token_type": "bearer"
}

HTTP Request

POST /oauth2/access_token

Form Fields

Parameter	Description
client_id	Your provisioned client ID
client_secret	Your provisioned client secret (required when authentication method is Client Secret POST)
client_assertion_type	The assertion type for authentication (required when authentication method is Client Secret JWT or Private Key JWT)
client_assertion	The JWT assertion for authentication (required when authentication method is Client Secret JWT or Private Key JWT)
refresh_token	The user's refresh token
grant_type	The OAuth 2.0 grant type ("refresh_token" should be used when using a refresh token to refresh the access token)

You will get a JSON response containing an access token and a new refresh token for the user. These tokens should be stored securely and not be exposed outside of making API calls to AdvicePay. Access tokens expire after 5 minutes. Refresh tokens are single-use and expire after 30 days.

5. Making API calls with your access token

For API calls, simply place the access token in the Authorization header.

Authorization: Bearer 228c9f52-c003

OAuth 2.0 Client Credentials

The Client Credentials flow is useful for enterprise account owner accounts acting on behalf of an integrating system. OAuth clients for firms with developer access can be added within the developer console. To enable the client credentials flow for your OAuth client, use the "Enable OAuth 2.0 Client Credentials Flow" toggle. The flow to authorize users for your app is:

Your site requests an access token using the client ID and client secret
Your site makes API calls using the access token

1. Requesting an access token using your client ID and client secret

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=client_credentials&client_id=yourClientID&client_secret=yourClientSecret" /oauth2/access_token

import "net/http"

// Build request
req, err := http.NewRequest("POST", "/oauth2/access_token", "grant_type=client_credentials&client_id=yourClientID&client_secret=yourClientSecret")
req.Header.Add("Content-Type", "application/x-www-form-urlencoded")
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "access_token": "228c9f52-c003", 
  "access_token_expires_at": 1606942087, 
  "scope": scope, 
  "token_type": "bearer"
}

HTTP Request

POST /oauth2/access_token

Form Fields

Parameter	Description
client_id	Your provisioned client ID
client_secret	Your provisioned client secret (required when authentication method is Client Secret POST)
client_assertion_type	The assertion type for authentication (required when authentication method is Client Secret JWT or Private Key JWT)
client_assertion	The JWT assertion for authentication (required when authentication method is Client Secret JWT or Private Key JWT)
grant_type	The OAuth 2.0 grant type ("client_credentials" should be used when using the client credentials flow to retrieve the access token)

You will get a JSON response containing an access token for the account owner. This token should be stored securely and not be exposed outside of making API calls to AdvicePay. Access tokens expire after 5 minutes.

2. Making API calls with your access token

For API calls, simply place the access token in the Authorization header.

Authorization: Bearer 228c9f52-c003

API Token (Deprecated)

This method is useful for a firm-level integration where all AdvicePay users are under the same account. API tokens are securely provisioned upon request and can be recycled upon request as well.

For API calls, place the API token in the Authorization header.

Authorization: Bearer api_token_here

OAuth 2.0 Authentication Methods

AdvicePay supports multiple authentication methods for obtaining an OAuth 2.0 token, depending on your needs. The authentication method can be set for your OAuth client in your developer dashboard.

Client Secret POST

This is the least secure authentication method because it involves sending the client secret in the body of each request to obtain a token. When you make the request to the access_token endpoint, simply include your provisioned client secret as the client_secret parameter in the request body.

Client Secret JWT

This is more secure because your client secret stays on your server. You'll generate a JWT and sign it with your client secret using HS256. When you make the request to the access_token endpoint, include the signed JWT as the client_assertion parameter in the request body. You'll also need to set the client_assertion_type parameter in the request body to urn:ietf:params:oauth:client-assertion-type:jwt-bearer.

Private Key JWT

This is the most secure way of obtaining a token. You'll use an asymmetric key pair for authentication. You'll generate a JWT and sign it with your private key using RS256. To use the Private Key JWT authentication method, you will need to upload your public key in your developer dashboard. We'll verify each request with the public key. When you make the request to the access_token endpoint, include the signed JWT as the client_assertion parameter in the request body. You'll also need to set the client_assertion_type parameter in the request body to urn:ietf:params:oauth:client-assertion-type:jwt-bearer.

JWT Format

The JWT Format

Claim	Description
aud	Required. The URL of the resource you're authenticating to. This will generally be https://app.advicepay.com/oauth2/access_token.
exp	Required. The unix timestamp for the expiration time of the token. We recommend keeping this short. If the request is received after the time indicated by exp, it will be rejected.
jti	Optional. The token identifier. If jti is used, AdvicePay will prevent the same jti from being used more than once. This mitigates replay attacks and is highly recommended.
iat	Required. The unix timstamp for when the token was issued. If the request is received before the time indicated by iat, it will be rejected.
iss	Required. The issuer of the token. This should always be your client ID.
sub	Required. The subject of the token. This should also always be your client ID.

The /me endpoint

This endpoint returns information about the user your API call is authorizing as.

curl /api/public/v1/me \
     -H "Authorization: Bearer advicepay_api_key"

import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/me", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "email":"example@advicepay.com",
  "parentID":32,
  "externalID":"abc123",
  "firstName":"first",
  "lastName":"last",
  "verified":true,
  "roleTitle":"Advisor",
  "parentRoleTitle":"Firm Manager",
  "accountOwner":false,
}

HTTP Request

GET /api/public/v1/me

Response

Value	Type	Description
id	number	This is the user's unique indentifier, and should be stored to do any future queries for data belonging to that user.
createdAt	number	This is the unix timestamp for when the user was created.
updatedAt	number	This is the unix timestamp for when the user was updated.
deletedAt	number	This is the unix timestamp for when the user was deleted.
email	string	The user's email address.
parentID	number	If the user is an Admin/Analyst, this is the ID of the user that this record is nested under.
parentRoleTitle	string	If the user is an Admin/Analyst, this is the Role of the user that this record is nested under.
externalID	string	This is used to specify an identifier from your system in the AdvicePay database.
firstName	string	User's first name.
lastName	string	User's last name.
verified	boolean	This reflects whether or not the user has verified their email and set a password.
roleTitle	string	This describes the user's specific role, and the implied abilities that go with that.
accountOwner	boolean	This describes whether the user is the owner of the account they are in.

Admins

Admins are only applicable to Professional and Enterprise accounts. Essential accounts do not support the admin user feature.

The Admin Object

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "email":"example@advicepay.com",
  "firstName":"first",
  "lastName":"last",
  "parentID":1,
  "roleTitle":"Admin"
}

Attributes

Value	Type	Description
id	number	This is the admin's unique indentifier.
createdAt	number	This is the unix timestamp for when the admin was created.
updatedAt	number	This is the unix timestamp for when the admin was updated.
deletedAt	number	This is the unix timestamp for when the admin was deleted.
email	string	This is validated for uniqueness.
firstName	string	Admin's first name.
lastName	string	Admin's last name.
parentID	number	This is the unique ID of the advisor whose account the admin is associated with.
roleTitle	string	This describes the admin's specific role, and the implied abilities that go with that.

List Admins

curl /api/public/v1/admins \
      -H "Authorization: Bearer advicepay_api_key" \

import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/admins", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "items": [
    {
      "id":1,
      "createdAt":1551201267,
      "updatedAt":1551201267,
      "deletedAt":0,
      "email":"example@advicepay.com",
      "firstName":"first",
      "lastName":"last",
      "parentID":1,
      "roleTitle":"Admin",
    },
    ...
  ],
  "page":1,
  "perPage":10,
  "totalItems":100,
  "totalPages":10
}

Required Permissions

User must be Managing Advisor, Full-access Advisor or Admin.

HTTP Request

GET /api/public/v1/admins

Query Parameters

Parameter	Default	Type	Description
page	1	number	This will determine which page to return.
perPage	10	number	This will determine the number of records to return (max is 100).
roleTitle	empty	string	Filter by whether the admin is a (developer, admin, or analyst).
email	empty	string	Filter by an admins's email.
parentID	empty	string	Filter by admins parentID.

Response

Returns a list of admins sorted by created_at in descending order

Get an Admin

curl /api/public/v1/admins/1 \
     -H "Authorization: Bearer advicepay_api_key"

import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/admins/1", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "email":"example@advicepay.com",
  "firstName":"first",
  "lastName":"last",
  "parentID":1,
  "roleTitle":"Admin",
}

Required Permissions

User must be an Advisor.

HTTP Request

GET /api/public/v1/admins/<ID>

URL Parameters

Parameter	Description
ID	The ID of the admin to fetch.

Response

Returns the requested admin

Create an Admin

curl /api/public/v1/admins \
      -H "Authorization: Bearer advicepay_api_key" \
      -d '{"email":"example@advicepay.com", "firstName":"first", "lastName":"last", "parentID":1, "disableDirectLogin":false, "permission":"Admin"}' \
      -X POST

import "net/http"

type createAdminReq struct {
  ParentID           uint   `json:"parentID"`
  Email              string `json:"email"`
  FirstName          string `json:"firstName"`
  LastName           string `json:"lastName"`
  Permission         string `json:"permission"`
  DisableDirectLogin bool   `json:"disableDirectLogin"`
  SSOID              string `json:"ssoID"`
}

// Marshall request data to JSON string
data := createAdminReq{
  ParentID:           1,
  Email:              "example@advicepay.com",
  FirstName:          "first",
  LastName:           "last",
  Permission:         "Admin",
  DisableDirectLogin: false,
}
jsonData, err := json.Marshal(data)
// ...

// Build request
req, err := http.NewRequest("POST", "/api/public/v1/admins", bytes.NewBuffer(jsonData))
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "email":"example@advicepay.com",
  "firstName":"first",
  "lastName":"last",
  "parentID":1,
  "roleTitle":"Admin",
}

Required Permissions

User must be Managing Advisor, Full-access Advisor or Admin.

HTTP Request

POST /api/public/v1/admins

Arguments

Value	Required	Type	Description
email	true	string	Email is validated for correct format and then to ensure it is unique for the given parentID.
firstName	true	string	Trailing or leading whitespaces will be trimmed.
lastName	true	string	Trailing or leading whitespaces will be trimmed.
permission	true	string	Must be one of the following: "Admin", "Analyst". "Admin" gives the same access and functionality as the parent user. "Analyst" gives read-only access to the parent user's account.
parentID	true	number	The unique ID of the advisor whose account the admin will associated with. Admins may be associated with any advisor with read and write permissions (Full-Access Advisor, Managing Advisor, Advisor). Analysts may be associated with any advisor with read permissions (Full-Access Advisor, Managing Advisor, Advisor, Read-only Advisor).
disableDirectLogin	false	boolean	If set to true, the admin will only be able to login using SSO.
ssoID	conditional	string	If disableDirectLogin is set to true, this field is required to enable SSO login. The ID will be your unique idenitifier to create the SSO link between AdvicePay and your platform.

Response

The newly created Admin object, if the call succeeded. If the request failed, this call returns an error.

Update an Admin

curl /api/public/v1/admins/1 \
      -H "Authorization: Bearer advicepay_api_key" \
      -d '{"email":"example@advicepay.com", "firstName":"first", "lastName":"last", "permission":"Admin", "disableDirectLogin": true, "ssoID": "12345"}' \
      -X PUT

import "net/http"

type updateAdminReq struct {
  Email              string `json:"email"`
  FirstName          string `json:"firstName"`
  LastName           string `json:"lastName"`
  Permission         string `json:"permission"`
  DisableDirectLogin bool   `json:"disableDirectLogin"`
  SSOID              string `json:"ssoID"`
}

// Marshall request data to JSON string
data := updateAdminReq{
  Email:              "example@advicepay.com"
  FirstName:          "first",
  LastName:           "last",
  Permission:         "Admin",
  DisableDirectLogin: false,
  SSOID:              "12345",
}
jsonData, err := json.Marshal(data)
// ...

// Build request
req, err := http.NewRequest("PUT", "/api/public/v1/admin/1", bytes.NewBuffer(jsonData))
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "email":"example@advicepay.com",
  "firstName":"first",
  "lastName":"last",
  "parentID":1,
  "roleTitle":"Admin",
}

Required Permissions

User must be Managing Advisor, Full-access Advisor or Admin.

HTTP Request

PUT /api/public/v1/admins/<ID>

URL Parameters

Parameter	Description
ID	The ID of the admin to update.

Arguments

Value	Required	Type	Description
email	false	string	Email is validated for correct format and then for uniqueness in our database. If this is not sent, the existing email address will be maintained.
firstName	false	string	Trailing or leading whitespaces will be trimmed. If this is not sent on the request, the existing first name will be maintained.
lastName	false	string	Trailing or leading whitespaces will be trimmed. If this is not sent on the request, the existing last name will be maintained.
permission	false	string	Must be one of the following: "Admin", "Analyst". "Admin" gives the same access and functionality as the parent user. "Analyst" gives read-only access to the parent user's account. If this is not sent on the request, the existing permission will be maintained.
disableDirectLogin	false	boolean	If set to true, the admin will only be able to login using SSO. If this is not sent on the request, the existing setting for disable direct login will be maintained.
ssoID	conditional	string	If disableDirectLogin is set to true, this field is required to enable SSO login. The ID will be your unique idenitifier to create the SSO link between AdvicePay and your platform. If this is not sent on the request, the existing SSO ID will be maintained.

Response

The updated Admin object, if the call succeeded. If the request failed, this call returns an error.

Delete an Admin

curl /api/public/v1/admins/1 \
      -H "Authorization: Bearer advicepay_api_key" \
      -X DELETE

import "net/http"

// Build request
req, err := http.NewRequest("DELETE", "/api/public/v1/admins/1", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "id":1
}

Required Permissions

User must be Managing Advisor, Full-access Advisor or Admin.

HTTP Request

DELETE /api/public/v1/admins/<ID>

URL Parameters

Parameter	Description
ID	The ID of the admin to delete.

Response

Returns the ID of the deleted admin

Advisors

Advisors are only applicable to Professional and Enterprise accounts. Essential accounts are single user and have no concept of multiple Advisors.

The Advisor Object

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "email":"example@advicepay.com",
  "externalID":"abc123",
  "firstName":"first",
  "lastName":"last",
  "verified":true,
  "roleTitle":"Advisor",
  "completedOnboarding":true,
  "officeID":1,
  "metadata":{
    "Phone": "888-888-8888"
  }
}

Attributes

Value	Type	Description
id	number	This is the advisor's unique indentifier, and should be stored to do any future queries for data belonging to that advisor.
createdAt	number	This is the unix timestamp for when the advisor was created.
updatedAt	number	This is the unix timestamp for when the advisor was updated.
deletedAt	number	This is the unix timestamp for when the advisor was deleted.
email	string	This is validated for uniqueness.
externalID	string	This is used to specify an identifier from your system in the AdvicePay database.
firstName	string	Advisor's first name.
lastName	string	Advisor's last name.
verified	boolean	This boolean is reflects whether or not the advisor has verified their email and set a password.
roleTitle	string	This describes the advisor's specific role, and the implied abilities that go with that.
completedOnboarding	boolean	This boolean is used to determine if the advisor should add banking information, and will be true in most cases when created via the API.
officeID	number	The ID of the office that the advisor has been assigned to.
metadata	object	Any additonal information added via a custom attribute will show here.

List Advisors

curl /api/public/v1/advisors \
     -H "Authorization: Bearer advicepay_api_key" \

import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/advisors", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "items": [
    {
      "id":1,
      "createdAt":1551201267,
      "updatedAt":1551201267,
      "deletedAt":0,
      "email":"example@advicepay.com",
      "externalID":"abc123",
      "firstName":"first",
      "lastName":"last",
      "verified":true,
      "roleTitle":"Advisor",
      "completedOnboarding":true,
      "officeID":1,
      "metadata":{"Input Field": "Test Input", "Dropdown Field": "Option 2", "Multi Tag Field": ["a", "b", "c"]}
    },
    ...
  ],
  "page":1,
  "perPage":10,
  "totalItems":100,
  "totalPages":10
}

Required Permissions

User must be Managing Advisor, Full-access Advisor or Admin.

HTTP Request

GET /api/public/v1/advisors

Query Parameters

Parameter	Default	Type	Description
page	1	number	This will determine which page to return.
perPage	10	number	This will determine the number of records to return (max is 100).
verified	empty	boolean	Filter by whether advisors have verified their email and set a password (automatically set to true if login is SSO only).
email	empty	string	Filter by advisor's email.
externalID	empty	string	Filter by advisor's externalID.
officeID	empty	number	Filter by advisor's office ID.

Response

Returns a list of advisors sorted by created_at in descending order

Get an Advisor

curl /api/public/v1/advisors/1 \
     -H "Authorization: Bearer advicepay_api_key"

import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/advisors/1", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "email":"example@advicepay.com",
  "firstName":"first",
  "lastName":"last",
  "verified":true,
  "roleTitle":"Advisor",
  "completedOnboarding":true,
  "officeID":1,
  "metadata":{
    "Phone": "888-888-8888"
  }
}

Required Permissions

User must be Managing Advisor, Full-access Advisor or Admin.

HTTP Request

GET /api/public/v1/advisors/<ID>

URL Parameters

Parameter	Description
ID	The ID of the advisor to fetch.

Response

Returns the requested advisor

Create an Advisor

curl /api/public/v1/advisors \
     -H "Authorization: Bearer advicepay_api_key" \
     -d '{"email":"example@advicepay.com", "firstName":"first", "lastName":"last", "permission":"Advisor", "disableDirectLogin":false, "externalID": "abc123", "officeID": 1}' \
     -X POST

import "net/http"

type createAdvisorReq struct {
  Email              string `json:"email"`
  ExternalID         string `json:"externalID"`
  FirstName          string `json:"firstName"`
  LastName           string `json:"lastName"`
  Permission         string `json:"permission"`
  DisableDirectLogin bool   `json:"disableDirectLogin"`
  SSOID              string `json:"ssoID"`
  OfficeID           uint   `json:"officeID"`
  Metadata           map[string]interface{}
}

// Marshall request data to JSON string
data := createAdvisorReq{
  Email:              "example@advicepay.com",
  ExternalID:         "abc123",
  FirstName:          "first",
  LastName:           "last",
  Permission:         "Advisor",
  DisableDirectLogin: false,
  Metadata:           map[string]interface{}{"Input Field": "Test Input", "Dropdown Field": "Option 2", "Multi Tag Field": []string{"a", "b", "c"}},
}
jsonData, err := json.Marshal(data)
// ...

// Build request
req, err := http.NewRequest("POST", "/api/public/v1/advisors", bytes.NewBuffer(jsonData))
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "email":"example@advicepay.com",
  "externalID":"abc123",
  "firstName":"first",
  "lastName":"last",
  "verified":true,
  "roleTitle":"Advisor",
  "completedOnboarding":true,
  "officeID":1,
  "metadata":{"Input Field": "Test Input", "Dropdown Field": "Option 2", "Multi Tag Field": ["a", "b", "c"]}
}

Required Permissions

User must be Managing Advisor, Full-access Advisor or Admin.

HTTP Request

POST /api/public/v1/advisors

Arguments

Value	Required	Type	Description
email	true	string	Email is validated for correct format and then for uniqueness in our database.
externalID	false	string	No validation or formatting enforced. Note that this is not the same as `ssoID`. It is also up to the caller to ensure uniqueness of the value.
firstName	true	string	Trailing or leading whitespaces will be trimmed.
lastName	true	string	Trailing or leading whitespaces will be trimmed.
permission	true	string	Must be one of the following: "Advisor", "Read-only Advisor", "No-login Advisor", "Managing Advisor", or "Full-access Advisor". "Advisor" gives full access to AdvicePay. "Read-only Advisor" gives login access but no power to invoice clients. "No-login Advisor" gives no login, and is completely managed by home office. "Managing Advisor" can see office-wide data. "Full-access Advisor" can see firm-wide data and update firm settings (note: Full-access Advisor permissions are only available to the Account Owner for enterprise firms. The request will be rejected if this is set on an enterprise advisor.).
disableDirectLogin	false	boolean	If set to true, the advisor will only be able to login using SSO.
ssoID	conditional	string	If disableDirectLogin is set to true, this field is required to enable SSO login. The ID will be your unique idenitifier to create the SSO link between AdvicePay and your platform.
officeID	conditional	number	If included, the advisor will be assigned to the specified office.
metadata	false	object	This is used to populate the metadata for the advisor.

Response

The newly created Advisor object, if the call succeeded. If the request failed, this call returns an error.

Update an Advisor

curl /api/public/v1/advisors/1 \
     -H "Authorization: Bearer advicepay_api_key" \
     -d '{"email":"example@advicepay.com", "firstName":"first", "lastName":"last", "permission":"Advisor", "externalID": "abc123", "officeID": 1}' \
     -X PUT

import "net/http"

type updateAdvisorReq struct {
  Email              string `json:"email"`
  ExternalID         string `json:"externalID"`
  FirstName          string `json:"firstName"`
  LastName           string `json:"lastName"`
  Permission         string `json:"permission"`
  DisableDirectLogin bool   `json:"disableDirectLogin"`
  SSOID              string `json:"ssoID"`
  OfficeID           uint   `json:"officeID"`
  Metadata           map[string]interface{}
}

// Marshall request data to JSON string
data := updateAdvisorReq{
  Email:              "example@advicepay.com"
  ExternalID:         "abc123",
  FirstName:          "first",
  LastName:           "last",
  Permission:         "Advisor",
  DisableDirectLogin: false,
  Metadata:           map[string]interface{}{"Input Field": "Test Input", "Dropdown Field": "Option 2", "Multi Tag Field": []string{"a", "b", "c"}},
}
jsonData, err := json.Marshal(data)
// ...

// Build request
req, err := http.NewRequest("PUT", "/api/public/v1/advisors/1", bytes.NewBuffer(jsonData))
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1561422442,
  "deletedAt":0,
  "email":"example@advicepay.com",
  "externalID":"abc123",
  "firstName":"first",
  "lastName":"last",
  "verified":true,
  "roleTitle":"Advisor",
  "completedOnboarding":true,
  "officeID":1,
  "metadata":{"Input Field": "Test Input", "Dropdown Field": "Option 2", "Multi Tag Field": ["a", "b", "c"]}
}

Required Permissions

User must be Managing Advisor, Full-access Advisor or Admin.

HTTP Request

PUT /api/public/v1/advisors/<ID>

URL Parameters

Parameter	Description
ID	The ID of the advisor to update.

Arguments

Value	Required	Type	Description
email	false	string	Email is validated for correct format and then for uniqueness in our database. If this is not sent, the existing email address will be maintained.
externalID	false	string	No validation or formatting enforced. Note that this is not the same as `ssoID`. It is also up to the caller to ensure uniqueness of the value. If this is not sent on the request, the existing external ID will be maintained.
firstName	false	string	Trailing or leading whitespaces will be trimmed. If this is not sent on the request, the existing first name will be maintained.
lastName	false	string	Trailing or leading whitespaces will be trimmed. If this is not sent on the request, the existing last name will be maintained.
permission	false	string	Must be one of the following: "Advisor", "Read-only Advisor", "No-login Advisor", "Managing Advisor", or "Full-access Advisor". "Advisor" gives full access to AdvicePay. "Read-only Advisor" gives login access but no power to invoice clients. "No-login Advisor" gives no login, and is completely managed by home office. "Managing Advisor" can see office-wide data. "Full-access Advisor" can see firm-wide data and update firm settings. If this is not sent on the request, the existing permission will be maintained.
disableDirectLogin	false	boolean	If set to true, the advisor will only be able to login using SSO. If this is not sent on the request, the existing setting for disable direct login will be maintained.
ssoID	conditional	string	If disableDirectLogin is set to true, this field is required to enable SSO login. The ID will be your unique idenitifier to create the SSO link between AdvicePay and your platform. If this is not sent on the request, the existing SSO ID will be maintained.
officeID	conditional	number	If included, the advisor will be assigned to the specified office. If this is not sent on the request, the existing office ID will be maintained.
metadata	false	object	This is used to populate the metadata for the advisor. If this is not sent on the request, the existing metadata will be maintained. If this is on the request, all existing metadata will be deleted.

Response

The updated Advisor object, if the call succeeded. If the request failed, this call returns an error.

Delete an Advisor

curl /api/public/v1/advisors/1 \
     -H "Authorization: Bearer advicepay_api_key" \
     -X DELETE

import "net/http"

// Build request
req, err := http.NewRequest("DELETE", "/api/public/v1/advisors/1", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "id":1
}

Required Permissions

User must be Managing Advisor, Full-access Advisor or Admin.

HTTP Request

DELETE /api/public/v1/advisors/<ID>

URL Parameters

Parameter	Description
ID	The ID of the advisor to delete.

Response

Returns the ID of the deleted advisor

Agreements

The Agreement Object

{
  "id":1,
  "completedAt":1551201267,
  "createdAt":1551201267,
  "deletedAt":0,
  "finalizedAt": 1551201268,
  "updatedAt":1551201268,
  "clientID":1,
  "advisorID":2,
  "engagementID":3,
  "invoiceID":1,
  "status":"agreement_status_complete",
  "signingOrderEnabled":true,
  "signers": [
    {
      "agreementID":1,
      "email":"example@advicepay.com",
      "name":"first last",
      "status":"signer_status_complete",
      "signedAt":1551201267,
      "completedAt":1551201267,
      "signingOrder":0,
      "title":"Client",
      "externalID":"abc123",
    }
  ],
  "template": {
    "name": "ExampleTemplate",
    "description": "Example eSign Template"
  }
}

Attributes

Value	Type	Description
id	number	This is the agreement's unique indentifier.
completedAt	number	This is the unix timestamp when all signers finished signing and the agreement was marked as complete. For uploaded documents, this is populated via the AdvicePay UI when the advisor uploads them.
createdAt	number	This is the unix timestamp for when the agreement was created.
deletedAt	number	This is the unix timestamp for when the agreement was deleted.
finalizedAt	number	This is the unix timestamp for when the agreement was finalized and marked as ready for download. This will never change once it is set. For eSigned documents, this is the date the last signer signs the document. For uploaded documents, this is the date the document was uploaded.
updatedAt	number	This is the unix timestamp for when the agreement was updated.
clientID	number	This is the unique AdvicePay ID of the client that the agreement was sent to. Since signer emails can be entered manually, it is possible for the Client ID to be 0, which indicates that no signers match up with a client record. An example scenario where a client record wouldn't exist is a document that needs to be signed by the advisor and the home office.
advisorID	number	This is the unique AdvicePay ID of the advisor that created the agreement.
engagementID	number	This is the ID of the engagement that the agreement belongs to.
invoiceID	number	This is the ID of the invoice that is related to the agreement.
status	string	This is status of the agreement. It will be one of: "agreement_status_created" (no action has been taken), "agreement_status_opened" (a signer has opened the document), "agreement_status_complete" (all signers have signed the document), "agreement_status_voided" (the signature request has been canceled), "agreement_status_draft" (the signature request needs to be completed before sending)
signingOrderEnabled	boolean	This is true if the agreement was sent to one signer at a time in a particular signing order.
fileNames	string list	For agreements uploaded to AdvicePay, the collection of file names of the uploaded PDFs. This will be empty if the agreement wasn't uploaded as a PDF.
signers	object list	The signers on the agreement. This will be empty if the agreement was uploaded as a PDF.
template	object	The template on the agreement. Warning: this will be null if the agreement was uploaded as a PDF.

List Agreements

curl /api/public/v1/agreements \
     -H "Authorization: Bearer advicepay_api_key" \

import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/agreements", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "items": [
    {
      "id":1,
      "completedAt":1551201267,
      "createdAt":1551201267,
      "deletedAt":0,
      "finalizedAt":1551201268,
      "updatedAt":1551201268,
      "clientID":1,
      "advisorID":2,
      "engagementID":3,
      "invoiceID":1,
      "status":"agreement_status_complete",
      "signingOrderEnabled":true,
      "signers": [
        {
          "agreementID":1,
          "email":"example@advicepay.com",
          "name":"first last",
          "status":"signer_status_complete",
          "signedAt":1551201267,
          "completedAt":1551201267,
          "signingOrder":0,
          "title":"Client",
          "externalID":"abc123",
        }
      ],
      "template": {
        "name": "ExampleTemplate",
        "description": "Example eSign Template"
      }
    },
    {
      "id": 2,
      "completedAt": 1663740000,
      "createdAt": 1664483269,
      "deletedAt": 0,
      "finalizedAt": 1664483269,
      "updatedAt": 1664483269,
      "advisorID": 2,
      "clientID": 1,
      "engagementID": 3,
      "invoiceID": 0,
      "templateID": 0,
      "status": "agreement_status_complete",
      "signingOrderEnabled": false,
      "fileNames": [
          "Blank+Document.pdf"
      ],
      "signers": [],
      "template": null
    }
    ...
  ],
  "page":1,
  "perPage":10,
  "totalItems":100,
  "totalPages":10
}

HTTP Request

GET /api/public/v1/agreements

Query Parameters

Parameter	Default	Type	Description
page	1	number	This will determine which page to return.
perPage	10	number	This will determine the number of records to return (max is 100).
advisorID	empty	number	Filter by agreement advisor.
clientID	empty	number	Filter by agreement client.
engagementID	empty	number	Filter by agreement engagement.
invoiceID	empty	number	Filter by agreement invoice.
status	empty	string	Filter by agreement status. Must be one of: "agreement_status_created", "agreement_status_opened", "agreement_status_complete", "agreement_status_voided".
completedAfter	empty	number	This is a unix timestamp to filter by completedAt. For most public API operations, we recommend using finalizedAfter.
completedBefore	empty	number	This is a unix timestamp to filter by completedAt. For most public API operations, we recommend using finalizedBefore.
finalizedAfter	empty	number	This is a unix timestamp to filter by finalizedAt.
finalizedBefore	empty	number	This is a unix timestamp to filter by finalizedAt.
updatedAfter	empty	number	This is a unix timestamp to filter by updatedAt.
updatedBefore	empty	number	This is a unix timestamp to filter by updatedAt.

Response

Returns a list of agreements sorted by created_at in descending order

Get an Agreement

curl /api/public/v1/agreements/1 \
     -H "Authorization: Bearer advicepay_api_key"

import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/agreements/1", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "id":1,
  "createdAt":1551201267,
  "deletedAt":0,
  "completedAt":1551201267,
  "finalizedAt":1551201268,
  "updatedAt":1551201268,
  "clientID":1,
  "advisorID":2,
  "engagementID":3,
  "invoiceID":1,
  "status":"agreement_status_complete",
  "signingOrderEnabled":true,
  "fileNames": [],
  "signers": [
    {
      "agreementID":1,
      "email":"example@advicepay.com",
      "name":"first last",
      "status":"signer_status_complete",
      "signedAt":1551201267,
      "completedAt":1551201267,
      "signingOrder":0,
      "title":"Client",
      "externalID":"abc123",
    }
  ],
  "template": {
    "name": "ExampleTemplate",
    "description": "Example eSign Template"
  }
}

HTTP Request

GET /api/public/v1/agreements/<ID>

URL Parameters

Parameter	Description
ID	The ID of the agreement to fetch.

Response

Returns the requested agreement

Download an Agreement

curl -O -J /api/public/v1/agreements/1/download?expect=json \
     -H "Authorization: Bearer advicepay_api_key"

import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/agreements/1/download?expect=json", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "data":"Base64-encoded Data Here",
}

HTTP Request

GET /api/public/v1/agreements/<ID>/download

URL Parameters

Parameter	Description
ID	The ID of the agreement to download.

Query Parameters

Parameter	Default	Type	Description
expect	binary	string	The expected response type. Must be one of "binary" (default) or "json".

Response

Returns a PDF file for the agreement. If "expect" query parameter is "binary" or omitted, the response will contain the binary representation of the file. The response header will have a "Content-Type" of "application/octet-stream" and "Content-Transfer-Encoding" of "binary". If "expect" query parameter is "json", the response will contain a file transfer object with a Base64-encoded representation of the file.

Clients

The Client Object

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "email":"example@advicepay.com",
  "externalID":"abc123",
  "firstName":"first",
  "lastName":"last",
  "invoiceDisplayName":"",
  "advisorID":1,
  "verified":false,
  "wealthboxURL":"",
  "metadata":{
    "Phone": "888-888-8888"
  }
}

Attributes

Value	Type	Description
id	number	This is the client's unique indentifier, and should be stored to do any future queries for data belonging to that client.
createdAt	number	This is the unix timestamp for when the client was created.
updatedAt	number	This is the unix timestamp for when the client was updated.
deletedAt	number	This is the unix timestamp for when the client was deleted.
email	string	This is validated for uniqueness.
externalID	string	This is used to specify an identifier from your system in the AdvicePay database.
firstName	string	Client's first name.
lastName	string	Client's last name.
invoiceDisplayName	string	The name to display on invoices. If left blank, the Client's first and last name will be used by default.
advisorID	number	This is the unique ID for the client's advisor.
verified	boolean	This boolean is reflects whether or not the client has verified their email and set a password.
wealthboxURL	string	This is used to easily go to Wealthbox from AdvicePay. This URL must begin with `https://app.crmworkspace.com/contacts/`.
metadata	object	Any additonal information added via a custom attribute will show here.

List Clients

curl /api/public/v1/clients \
     -H "Authorization: Bearer advicepay_api_key" \

import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/clients", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "items": [
    {
      "id":1,
      "createdAt":1551201267,
      "updatedAt":1551201267,
      "deletedAt":0,
      "email":"example@advicepay.com",
      "externalID":"abc123",
      "firstName":"first",
      "lastName":"last",
      "advisorID":1,
      "verified":false,
      "invoiceDisplayName":"",
      "wealthboxURL":"",
      "metadata":{"Input Field": "Test Input", "Dropdown Field": "Option 2", "Multi Tag Field": ["a", "b", "c"]}
    },
    ...
  ],
  "page":1,
  "perPage":10,
  "totalItems":100,
  "totalPages":10
}

HTTP Request

GET /api/public/v1/clients

Query Parameters

Parameter	Default	Type	Description
page	1	number	This will determine which page to return.
perPage	10	number	This will determine the number of records to return (max is 100).
advisorID	empty	number	Filter by client advisor.
verified	empty	boolean	Filter by whether clients have verified their email and set a password.
email	empty	string	Filter by client's email.
name	empty	string	Filter by client's first and/or last name. This is a case insensitive fuzzy match.
externalID	empty	string	Filter by client's externalID.

Response

Returns a list of clients sorted by created_at in descending order

Get a Client

curl /api/public/v1/clients/1 \
     -H "Authorization: Bearer advicepay_api_key"

import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/clients/1", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "email":"example@advicepay.com",
  "firstName":"first",
  "lastName":"last",
  "invoiceDisplayName":"",
  "advisorID":1,
  "verified":false,
  "wealthboxURL":"",
  "metadata":{
    "Phone": "888-888-8888"
  }
}

HTTP Request

GET /api/public/v1/clients/<ID>

URL Parameters

Parameter	Description
ID	The ID of the client to fetch.

Response

Returns the requested client

Create a Client

Essential accounts are limited to 10 Clients.

curl /api/public/v1/clients \
     -H "Authorization: Bearer advicepay_api_key" \
     -d '{"email":"example@advicepay.com", "firstName":"first", "lastName":"last", "advisorID":1, "externalID": "abc123", "metadata": {"Input Field": "Test Input", "Dropdown Field": "Option 2", "Multi Tag Field": ["a", "b", "c"]}}' \
     -X POST

import "net/http"

type createClientReq struct {
  AdvisorID          uint
  Email              string
  ExternalID         string
  FirstName          string
  LastName           string
  InvoiceDisplayName string
  WealthboxURL       string
  Metadata           map[string]interface{}
}

// Marshall request data to JSON string
data := createClientReq{
  AdvisorID:  1,
  Email:      "example@advicepay.com",
  ExternalID: "abc123",
  FirstName:  "first",
  LastName:   "last",
  Metadata: map[string]interface{}{"Input Field": "Test Input", "Dropdown Field": "Option 2", "Multi Tag Field": []string{"a", "b", "c"}},
}
jsonData, err := json.Marshal(data)
// ...

// Build request
req, err := http.NewRequest("POST", "/api/public/v1/clients", bytes.NewBuffer(jsonData))
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "email":"example@advicepay.com",
  "externalID":"abc123",
  "firstName":"first",
  "lastName":"last",
  "invoiceDisplayName":"",
  "advisorID":1,
  "verified":false,
  "wealthboxURL":"",
  "metadata":{"Input Field": "Test Input", "Dropdown Field": "Option 2", "Multi Tag Field": ["a", "b", "c"]}
}

Required Permissions

User must be Managing Advisor, Full-access Advisor or Admin.

HTTP Request

POST /api/public/v1/clients

Arguments

Value	Required	Type	Description
email	true	string	Email is validated for correct format and then to ensure it is unique for the given advisorID.
externalID	false	string	No validation or formatting enforced. If the authorized user does not have permission to change Client IDs, any provided value will be ignored.
firstName	true	string	Trailing or leading whitespaces will be trimmed.
lastName	true	string	Trailing or leading whitespaces will be trimmed.
invoiceDisplayName	false	string	The name to display on invoices. If left blank, the Client's first and last name will be used by default. Trailing or leading whitespaces will be trimmed.
advisorID	false	number	This will create the client and advisor relationship. If not provided, it will default to the authorized user's ID (or Parent ID for Admin roles)
disableDirectLogin	false	boolean	If set to true, the client will only be able to login using SSO.
ssoID	conditional	string	If disableDirectLogin is set to true, this field is required to enable SSO login. The ID will be your unique idenitifier to create the SSO link between AdvicePay and your platform.
wealthboxURL	false	string	This is used to easily go to Wealthbox from AdvicePay. This URL must begin with `https://app.crmworkspace.com/contacts/`.
metadata	false	object	This is used to populate the metadata for the client.

Response

The newly created Client object, if the call succeeded. If the request failed, this call returns an error.

Update a Client

curl /api/public/v1/clients/2 \
     -H "Authorization: Bearer advicepay_api_key" \
     -d '{"email":"example@advicepay.com", "firstName":"first", "lastName":"last", "advisorID":1, "externalID": "abc123", "metadata": {"Input Field": "Test Input", "Dropdown Field": "Option 2", "Multi Tag Field": ["a", "b", "c"]}}' \
     -X PUT

import "net/http"

type updateClientReq struct {
  AdvisorID          uint
  Email              string
  ExternalID         string
  FirstName          string
  LastName           string
  InvoiceDisplayName string
  WealthboxURL       string
  Metadata           map[string]interface{}
}

// Marshall request data to JSON string
data := updateClientReq{
  AdvisorID:  1,
  Email:      "example@advicepay.com",
  ExternalID: "abc123",
  FirstName:  "first",
  LastName:   "last",
  Metadata: map[string]interface{}{"Input Field": "Test Input", "Dropdown Field": "Option 2", "Multi Tag Field": []string{"a", "b", "c"}},
}
jsonData, err := json.Marshal(data)
// ...

// Build request
req, err := http.NewRequest("PUT", "/api/public/v1/clients/2", bytes.NewBuffer(jsonData))
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "id":2,
  "createdAt":1551201267,
  "updatedAt":1551201278,
  "deletedAt":0,
  "email":"example@advicepay.com",
  "externalID":"abc123",
  "firstName":"first",
  "lastName":"last",
  "invoiceDisplayName":"",
  "advisorID":1,
  "verified":false,
  "wealthboxURL":"",
  "metadata":{"Input Field": "Test Input", "Dropdown Field": "Option 2", "Multi Tag Field": ["a", "b", "c"]}
}

Required Permissions

User must be Managing Advisor, Full-access Advisor or Admin.

HTTP Request

PUT /api/public/v1/clients/<ID>

URL Parameters

Parameter	Description
ID	The ID of the client to update.

Arguments

Value	Required	Type	Description
email	false	string	Email is validated for correct format and then for uniqueness in our database. Note that client emails can only be updated prior to the client or their authorized users creating a payment method. If this is not sent on the request, the existing email will be maintained.
externalID	false	string	No validation or formatting enforced. If the authorized user does not have permission to change Client IDs, any provided value will be ignored. If this is not sent on the request, the existing external ID will be maintained.
firstName	false	string	Trailing or leading whitespaces will be trimmed. If this is not sent on the request, the existing first name will be maintained.
lastName	false	string	Trailing or leading whitespaces will be trimmed. If this is not sent on the request, the existing last name will be maintained.
invoiceDisplayName	false	string	The name to display on invoices. Trailing or leading whitespaces will be trimmed. If this is not sent on the request, the existing invoice display name will be maintained.
advisorID	false	number	This will create the client and advisor relationship. If this is not sent on the request, the existing advisor ID will be maintained.
disableDirectLogin	false	boolean	If set to true, the client will only be able to login using SSO.
ssoID	conditional	string	If disableDirectLogin is set to true, this field is required to enable SSO login. The ID will be your unique idenitifier to create the SSO link between AdvicePay and your platform.
wealthboxURL	false	string	This is used to easily go to Wealthbox from AdvicePay. This URL must begin with `https://app.crmworkspace.com/contacts/`. If this is not sent on the request, the existing Wealthbox URL will be maintained.
metadata	false	object	This is used to populate the metadata for the client. If this is not sent on the request, the existing metadata will be maintained. If this is on the request, all existing metadata will be deleted.

Response

The updated Client object, if the call succeeded. If the request failed, this call returns an error.

Custom Attributes

The Custom Attribute Object

{
    "id": 1,
    "createdAt": 1588366251,
    "updatedAt": 1588623099,
    "deletedAt": 0,
    "name": "My Text Field",
    "type": "text",
    "options": [],
    "description": "Enter text in this field.",
    "order": 1,
    "required": true,
    "visible": true
}

Attributes

Value	Type	Description
id	number	This is the attribute's unique indentifier.
createdAt	number	This is the unix timestamp for when the attribute was created.
updatedAt	number	This is the unix timestamp for when the attribute was updated.
deletedAt	number	This is the unix timestamp for when the attribute was deleted.
name	string	This is the name of the attribute (The field label on the UI).
type	string	This is the type of the attribute. Values for this can be "text" for text inputs, "select" for dropdowns, or "tags" for multi-tag fields.
options	string list	This is the list of options for the "select" attribute type.
description	string	This is the friendly description of how to use the attribute.
order	number	This is the order that the field appears on the screen in the UI.
required	boolean	This indicates whether an entry in field is required.
visible	boolean	This indicates that the field is hidden on the UI.

List Client Attributes

curl /api/public/v1/client_attributes \
     -H "Authorization: Bearer advicepay_api_key" \

import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/client_attributes", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
    "items": [
        {
            "id": 1,
            "createdAt": 1588366251,
            "updatedAt": 1588623099,
            "deletedAt": 0,
            "name": "My Text Field",
            "type": "text",
            "options": [],
            "description": "Enter text in this field.",
            "order": 1,
            "required": true,
            "visible": true
        },
        {
            "id": 2,
            "createdAt": 1604087954,
            "updatedAt": 1604087954,
            "deletedAt": 0,
            "name": "My Dropdown",
            "type": "select",
            "options": [
                "Option 1",
                "Option 2"
            ],
            "description": "Select a value.",
            "order": 2,
            "required": true,
            "visible": true
        },
        {
            "id": 3,
            "createdAt": 1604088359,
            "updatedAt": 1604088359,
            "deletedAt": 0,
            "name": "My Multi-tag",
            "type": "tags",
            "options": [],
            "description": "Tag this field with multiple values.",
            "order": 3,
            "required": true,
            "visible": true
        }
    ],
    "page": 1,
    "perPage": 10,
    "totalItems": 3,
    "totalPages": 1,
    "unknownTotal": false,
    "hasMore": false
}

HTTP Request

GET /api/public/v1/client_attributes

Query Parameters

Parameter	Default	Type	Description
page	1	number	This will determine which page to return.
perPage	10	number	This will determine the number of records to return (max is 100).

Response

Returns a list of custom attributes sorted by created_at in descending order

List Advisor Attributes

curl /api/public/v1/advisor_attributes \
     -H "Authorization: Bearer advicepay_api_key" \

import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/advisor_attributes", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
    "items": [
        {
            "id": 1,
            "createdAt": 1588366251,
            "updatedAt": 1588623099,
            "deletedAt": 0,
            "name": "My Text Field",
            "type": "text",
            "options": [],
            "description": "Enter text in this field.",
            "order": 1,
            "required": true,
            "visible": true
        },
        {
            "id": 2,
            "createdAt": 1604087954,
            "updatedAt": 1604087954,
            "deletedAt": 0,
            "name": "My Dropdown",
            "type": "select",
            "options": [
                "Option 1",
                "Option 2"
            ],
            "description": "Select a value.",
            "order": 2,
            "required": true,
            "visible": true
        },
        {
            "id": 3,
            "createdAt": 1604088359,
            "updatedAt": 1604088359,
            "deletedAt": 0,
            "name": "My Multi-tag",
            "type": "tags",
            "options": [],
            "description": "Tag this field with multiple values.",
            "order": 3,
            "required": true,
            "visible": true
        }
    ],
    "page": 1,
    "perPage": 10,
    "totalItems": 3,
    "totalPages": 1,
    "unknownTotal": false,
    "hasMore": false
}

HTTP Request

GET /api/public/v1/advisor_attributes

Query Parameters

Parameter	Default	Type	Description
page	1	number	This will determine which page to return.
perPage	10	number	This will determine the number of records to return (max is 100).

Response

Returns a list of custom attributes sorted by created_at in descending order

Deliverables

The Deliverable Template Object

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "name":"My Template"
  "detailedEvidenceTypes":{"file":{"visible":true,"required":false}},
  "esignTemplateExternalID":"ext123"
  "dueDateType":"calculate"
  "dueDateIntervalType":"years",
  "dueDateInterval":1,
  "dueDateTrigger":"invoice_paid"
  "recurring":true
  "recurringIntervalType":"years"
  "recurringInterval":1
  "recurringTrigger":"last_completed_deliverable"
  "maxRecurrence":2
  "allowedFileTypes":[".png",".jpg",".pdf",".docx"],
}

Attributes

Value	Type	Description
id	number	This is the template's unique indentifier, and should be stored to do any future queries for data belonging to that template.
createdAt	number	This is the unix timestamp for when the template was created.
updatedAt	number	This is the unix timestamp for when the template was updated.
deletedAt	number	This is the unix timestamp for when the template was deleted.
name	string	The name of the template.
detailedEvidenceTypes	object	The types of evidence that can be used for the template. Valid keys are "file", "url", "esign", "notes" and "attestation". Each has an object with 2 values visible and required. Visible determines whether or not they can see/submit that evidence type.
esignTemplateExternalID	string	The eSign template that will be used for evidence if "esign" is included in detailedEvidenceTypes.
dueDateType	string	Valid values are "specify", "calculate".
dueDateIntervalType	string	This is the interval type used to determine when the deliverable is due. Valid values are "days", "weeks", "months", and "years".
dueDateInterval	number	This is the interval specified in dueDateIntervalType units.
dueDateTrigger	string	This is the trigger used to calculate when the deliverable is due. Valid values are "invoice_paid" and "agreement_signed".
recurring	boolean	Recurring deliverables will automatically create a new deliverable when triggered and assign it to the same advisor.
recurringIntervalType	string	This is the interval type used to determine when the deliverable is due. Valid values are "days", "weeks", "months", and "years".
recurringInterval	number	This is the interval specified in recurringIntervalType units.
recurringTrigger	string	This is the trigger used to calculate when the deliverable is due. Valid value "last_completed_deliverable".
maxRecurrence	number	Total number of deliverables owed.
allowedFileTypes	string list	The only file types that can be submitted on deliverables. Valid file types are [".png",".jpg",".pdf",".docx"]

The Deliverable Object

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "advisorID":1,
  "clientID":2,
  "engagementID":3,
  "status":"open",
  "templateName":"My Template",
  "triggerDate":1234567,
  "dueDate":1234567,
  "attestation":false,
  "notes":"",
  "urls":[],
  "fileNames":[],
  "allowedFileTypes":[],
  "intervalType":"years",
  "interval":1,
  "trigger":"invoice_paid",
  "advisor":{},
  "client":{}
}

Attributes

Value	Type	Description
id	number	This is the deliverable's unique indentifier, and should be stored to do any future queries for data belonging to that deliverable.
createdAt	number	This is the unix timestamp for when the deliverable was created.
updatedAt	number	This is the unix timestamp for when the deliverable was updated.
deletedAt	number	This is the unix timestamp for when the deliverable was deleted.
advisorID	number	This is the unique identifier of the advisor that the deliverable was assigned to.
clientID	number	This is the unique identifier of the client that the deliverable is associated with.
engagementID	number	This is the unique identifier of the engagement that the deliverable belongs to.
status	string	This is the status of the deliverable. Valid values are "open", "complete", "upcoming", and "past_due".
templateName	string	The name of the template used to create the deliverable.
triggerDate	number	This is the unix timestamp for when the deliverable was triggered.
dueDate	number	This is the unix timestamp for when the deliverable is due.
attestation	boolean	A boolean whether or not the advisor attests to "providing the agreed upon services to the client and the included evidence is accurate".
notes	string	If the template allows notes as evidence, these are the notes.
urls	string list	If the template allows URLs as evidence, this contains the list of URLs.
fileNames	string list	If the template allows files to be uploaded as evidence, this contains the list of file names.
allowedFileTypes	string list	The only file types that can be submitted on a deliverable. Valid file types are [".png",".jpg",".pdf",".docx"]
intervalType	string	This is the interval type specified in the template. Valid values are "days", "weeks", "months", and "years".
interval	number	This is the interval specified in the template.
trigger	string	This is the trigger used to calculate when the deliverable is due. Valid values are "invoice_paid" and "agreement_signed".
advisor	object	The advisor on the deliverable.
client	object	The client on the deliverable.

List Deliverable Templates

curl /api/public/v1/deliverable_templates \
     -H "Authorization: Bearer advicepay_api_key" \

import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/deliverable_templates", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "items": [
    {
      "id":1,
      "createdAt":1551201267,
      "updatedAt":1551201267,
      "deletedAt":0,
      "name":"My Template"
      "detailedEvidenceTypes":{"file":{"visible":true,"required":false}},
      "esignTemplateExternalID":"ext123"
      "dueDateType":"calculate"
      "dueDateIntervalType":"years",
      "dueDateInterval":1,
      "dueDateTrigger":"invoice_paid"
      "recurring":true
      "recurringIntervalType":"years"
      "recurringInterval":1
      "recurringTrigger":"last_completed_deliverable"
      "maxRecurrence":2,
      "allowedFileTypes":[".png",".jpg",".pdf",".docx"]
    },
    ...
  ],
  "page":1,
  "perPage":10,
  "totalItems":100,
  "totalPages":10
}

HTTP Request

GET /api/public/v1/deliverable_templates

Query Parameters

Parameter	Default	Type	Description
page	1	number	This will determine which page to return.
perPage	10	number	This will determine the number of records to return (max is 100).

Response

Returns a list of deliverable templates sorted by created_at in descending order

Get a Deliverable Template

curl /api/public/v1/deliverable_templates/1 \
     -H "Authorization: Bearer advicepay_api_key"

import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/deliverable_templates/1", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "name":"My Template"
  "detailedEvidenceTypes":{"file":{"visible":true,"required":false}},,
  "esignTemplateExternalID":"ext123"
  "dueDateType":"calculate"
  "dueDateIntervalType":"years",
  "dueDateInterval":1,
  "dueDateTrigger":"invoice_paid"
  "recurring":true
  "recurringIntervalType":"years"
  "recurringInterval":1
  "recurringTrigger":"last_completed_deliverable"
  "maxRecurrence":2,
  "allowedFileTypes":[".png",".jpg",".pdf",".docx"]
}

HTTP Request

GET /api/public/v1/deliverable_templates/<ID>

URL Parameters

Parameter	Description
ID	The ID of the deliverable template to fetch.

Response

Returns the requested deliverable template

Create a Deliverable Template

curl /api/public/v1/deliverable_templates \
     -H "Authorization: Bearer advicepay_api_key" \
     -d '{"name":"My Template", "detailedEvidenceTypes":{"file":{"visible":true,"required":false}},, "intervalType":"years", "interval":1, "trigger":"invoice_paid", "allowedFileTypes":[".pdf",".png",".docx",".jpg"]}' \
     -X POST

import "net/http"

type createDeliverableTemplateReq struct {
  Name                  string
  DetailedEvidenceTypes map[string]interface{}
  DueDateType           string
  IntervalType          string
  Interval              uint
  Trigger               string
  AllowedFileTypes      []string
}

// Marshall request data to JSON string
data := createDeliverableTemplateReq{
  Name:                   "My Template",
  DetailedEvidenceTypes:  map[string]interface{}{"attestation":{"visible":true,"required":false}},
  DueDateType:            "calculate"
  DueDateIntervalType:    "years",
  DueDateInterval:        1,
  DueDateTrigger:         "invoice_paid",
  AllowedFileTypes:       [".pdf",".png",".docx",".jpg"],
}
jsonData, err := json.Marshal(data)
// ...

// Build request
req, err := http.NewRequest("POST", "/api/public/v1/deliverable_templates", bytes.NewBuffer(jsonData))
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "name":"My Template"
  "detailedEvidenceTypes":{"file":{"visible":true,"required":false}},
  "esignTemplateExternalID":""
  "dueDateType":"calculate"
  "dueDateIntervalType":"years",
  "dueDateInterval":1,
  "dueDateTrigger":"invoice_paid",
  "recurring":false,
  "recurringIntervalType":"",
  "recurringInterval":0,
  "recurringTrigger":"",
  "maxRecurrence":0,
  "allowedFileTypes":[".pdf",".png",".docx",".jpg"]
}

Required Permissions

User must be Full-access Advisor or Admin.

HTTP Request

POST /api/public/v1/deliverable_templates

Arguments

Value	Required	Type	Description
name	true	string	The name of the template.
detailedEvidenceTypes	true	object	The types of evidence that can be used for the template. Valid keys are "file", "url", "esign", "notes" and "attestation". Each has an object with 2 values visible and required. Visible determines whether or not they can see/submit that evidence type.
esignTemplateExternalID	conditional	string	If "esign" is included in evidenceTypes, this field is required. The eSign template that will be used for evidence if "esign" is included in evidenceTypes.
dueDateType	true	string	Valid values are "specify", "calculate".
dueDateIntervalType	conditional	string	If dueDateType is set to "calculate", this field is required. This is the interval type used to determine when the deliverable is due. Valid values are "days", "weeks", "months", and "years".
dueDateInterval	conditional	number	If dueDateType is set to "calculate", this field is required. This is the interval specified in dueDateIntervalType units.
dueDateTrigger	conditional	string	If dueDateType is set to "calculate", this field is required. This is the trigger used to calculate when the deliverable is due. Valid values are "invoice_paid" and "agreement_signed".
recurring	false	boolean	Recurring deliverables will automatically create a new deliverable when triggered and assign it to the same advisor.
recurringIntervalType	conditional	string	If recurring is set to true, this field is required. This is the interval type used to determine when the deliverable is due. Valid values are "days", "weeks", "months", and "years".
recurringInterval	conditional	number	If recurring is set to true, this field is required. This is the interval specified in recurringIntervalType units.
recurringTrigger	conditional	string	If recurring is set to true, this field is required. This is the trigger used to calculate when the deliverable is due. Valid value "last_completed_deliverable".
maxRecurrence	false	number	Total number of deliverables owed.
allowedFileTypes	false	string list	The only file types that can be submitted on a deliverable. Valid file types are [".png",".jpg",".pdf",".docx"]

Response

The newly created deliverable template object, if the call succeeded. If the request failed, this call returns an error.

Update a Deliverable Template

curl /api/public/v1/deliverable_templates/2 \
     -H "Authorization: Bearer advicepay_api_key" \
     -d '{"advisorID":1, "clientID":2, "triggerDate":1234567}' \
     -X PUT

import "net/http"

type updateDeliverableTemplateReq struct {
  Name          string
  DetailedEvidenceTypes map[string]interface{}
  DueDateIntervalType  string
  DueDateInterval      uint
  DueDateTrigger       string
  AllowedFileTypes     []string
}

// Marshall request data to JSON string
data := updateDeliverableTemplateReq{
  Name:          "My Template",
  DetailedEvidenceTypes:  map[string]interface{}{"attestation":{"visible":true,"required":false}},
  DueDateIntervalType:  "years",
  DueDateInterval:      1,
  DueDateTrigger:       "invoice_paid",
  AllowedFileTypes:     [".png",".jpg",".pdf",".docx"],
}
jsonData, err := json.Marshal(data)
// ...

// Build request
req, err := http.NewRequest("PUT", "/api/public/v1/deliverable_templates/2", bytes.NewBuffer(jsonData))
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "name":"My Template"
  "detailedEvidenceTypes":{"file":{"visible":true,"required":false}},
  "esignTemplateExternalID":""
  "dueDateType":"calculate"
  "dueDateIntervalType":"years",
  "dueDateInterval":1,
  "dueDateTrigger":"invoice_paid",
  "recurring":false,
  "recurringIntervalType":"",
  "recurringInterval":0,
  "recurringTrigger":"",
  "maxRecurrence":0,
  "allowedFileTypes":[".png",".jpg",".pdf",".docx"]
}

Required Permissions

User must be Full-access Advisor or Admin.

HTTP Request

PUT /api/public/v1/deliverable_templates/<ID>

URL Parameters

Parameter	Description
ID	The ID of the deliverable template to update.

Arguments

Value	Required	Type	Description
name	false	string	The name of the template.
detailedEvidenceTypes	false	object	The types of evidence that can be used for the template. Valid keys are "file", "url", "esign", "notes" and "attestation". Each has an object with 2 values visible and required. Visible determines whether or not they can see/submit that evidence type.
esignTemplateExternalID	conditional	string	If "esign" is included in evidenceTypes, this field is required. The eSign template that will be used for evidence if "esign" is included in evidenceTypes.
dueDateType	true	string	Valid values are "specify", "calculate".
dueDateIntervalType	conditional	string	If dueDateType is set to "calculate", this field is required. This is the interval type used to determine when the deliverable is due. Valid values are "days", "weeks", "months", and "years".
dueDateInterval	conditional	number	If dueDateType is set to "calculate", this field is required. This is the interval specified in dueDateIntervalType units.
dueDateTrigger	conditional	string	If dueDateType is set to "calculate", this field is required. This is the trigger used to calculate when the deliverable is due. Valid values are "invoice_paid" and "agreement_signed".
recurring	false	boolean	Recurring deliverables will automatically create a new deliverable when triggered and assign it to the same advisor.
recurringIntervalType	conditional	string	If recurring is set to true, this field is required. This is the interval type used to determine when the deliverable is due. Valid values are "days", "weeks", "months", and "years".
recurringInterval	conditional	number	If recurring is set to true, this field is required. This is the interval specified in recurringIntervalType units.
recurringTrigger	conditional	string	If recurring is set to true, this field is required. This is the trigger used to calculate when the deliverable is due. Valid value "last_completed_deliverable".
maxRecurrence	false	number	Total number of deliverables owed.
allowedFileTypes	false	string list	The only file types that can be submitted on a deliverable. Valid file types are [".png",".jpg",".pdf",".docx"]

Response

The updated deliverable template object, if the call succeeded. If the request failed, this call returns an error.

List Deliverables

curl /api/public/v1/deliverables?statuses[]=past_due&statuses[]=open \
     -H "Authorization: Bearer advicepay_api_key" \

import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/deliverables?statuses[]=past_due&statuses[]=open", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "items": [
    {
      "id":1,
      "createdAt":1551201267,
      "updatedAt":1551201267,
      "deletedAt":0,
      "advisorID":1,
      "clientID":2,
      "engagementID":3,
      "status":"open",
      "templateName":"My Template",
      "triggerDate":1234567,
      "dueDate":1234567,
      "attestation":false,
      "notes":"",
      "urls":[],
      "fileNames":[],
      "allowedFileTypes":[".png",".jpg",".pdf",".docx"],
      "intervalType":"years",
      "interval":1,
      "trigger":"invoice_paid",
      "advisor":{},
      "client":{}
    },
    ...
  ],
  "page":1,
  "perPage":10,
  "totalItems":100,
  "totalPages":10
}

HTTP Request

GET /api/public/v1/deliverables

Query Parameters

Parameter	Default	Type	Description
page	1	number	This will determine which page to return.
perPage	10	number	This will determine the number of records to return (max is 100).
statuses	empty	string list	This will only return deliverables with the specified statuses.
advisorIDs	empty	string list	This will only return deliverables for the specified advisors.
clientIDs	empty	string list	This will only return deliverables for the specified clients.
engagementID	empty	number	This will only return deliverables with the specified engagement ID.
dueDateMin	empty	number	This will only return deliverables with a minimum due date of the specified unix epoch.
dueDateMax	empty	number	This will only return deliverables with a maximum due date of the specified unix epoch.
completedAfter	empty	number	This is a unix timestamp to filter by completedAt.
completedBefore	empty	number	This is a unix timestamp to filter by completedAt.
updatedAfter	empty	number	This is a unix timestamp to filter by updatedAt.
updatedBefore	empty	number	This is a unix timestamp to filter by updatedAt.

Response

Returns a list of deliverables sorted by created_at in descending order

Get a Deliverable

curl /api/public/v1/deliverables/1 \
     -H "Authorization: Bearer advicepay_api_key"

import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/deliverables/1", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "advisorID":1,
  "clientID":2,
  "engagementID":3,
  "status":"open",
  "templateName":"My Template",
  "triggerDate":1234567,
  "dueDate":1234567,
  "attestation":false,
  "notes":"",
  "urls":[],
  "fileNames":[],
  "allowedFileTypes":[".png",".jpg",".pdf",".docx"],
  "intervalType":"years",
  "interval":1,
  "trigger":"invoice_paid",
  "advisor":{},
  "client":{}
}

HTTP Request

GET /api/public/v1/deliverables/<ID>

URL Parameters

Parameter	Description
ID	The ID of the deliverable to fetch.

Response

Returns the requested deliverable

Create a Deliverable

curl /api/public/v1/deliverables \
     -H "Authorization: Bearer advicepay_api_key" \
     -d '{"templateID":1, "advisorID":1, "clientID":2, "triggerDate":1234567}' \
     -X POST

import "net/http"

type createDeliverableReq struct {
  TemplateID         uint
  AdvisorID          uint
  ClientID           uint
  TriggerDate        uint64
}

// Marshall request data to JSON string
data := createDeliverableReq{
  TemplateID:  1
  AdvisorID:   1,
  ClientID:    2,
  TriggerDate: 1234567,
}
jsonData, err := json.Marshal(data)
// ...

// Build request
req, err := http.NewRequest("POST", "/api/public/v1/deliverables", bytes.NewBuffer(jsonData))
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "advisorID":1,
  "clientID":2,
  "engagementID":3,
  "status":"open",
  "templateName":"My Template",
  "triggerDate":1234567,
  "dueDate":1234567,
  "attestation":false,
  "notes":"",
  "urls":[],
  "fileNames":[],
  "allowedFileTypes":[".png",".jpg",".pdf",".docx"],
  "intervalType":"years",
  "interval":1,
  "trigger":"invoice_paid",
  "advisor":{},
  "client":{}
}

Required Permissions

User must be Full-access Advisor or Admin.

HTTP Request

POST /api/public/v1/deliverables

Arguments

Value	Required	Type	Description
templateID	true	number	This is the ID of the template to use when creating the deliverable.
advisorID	true	number	This will create the deliverable and advisor relationship.
clientID	true	number	This will create the deliverable and client relationship.
triggerDate	true	number	This is the unix timestamp used to calculate the date the deliverable is due.

Response

The newly created deliverable object, if the call succeeded. If the request failed, this call returns an error.

Update a Deliverable

curl /api/public/v1/deliverables/2 \
     -H "Authorization: Bearer advicepay_api_key" \
     -d '{"advisorID":1, "clientID":2, "triggerDate":1234567}' \
     -X PUT

import "net/http"

type updateDeliverableReq struct {
  AdvisorID   uint
  ClientID    uint
  TriggerDate uint64
}

// Marshall request data to JSON string
data := updateDeliverableReq{
  AdvisorID:   3,
  ClientID:    4,
  TriggerDate: 12345678,
}
jsonData, err := json.Marshal(data)
// ...

// Build request
req, err := http.NewRequest("PUT", "/api/public/v1/deliverables/2", bytes.NewBuffer(jsonData))
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "advisorID":1,
  "clientID":2,
  "engagementID":3,
  "status":"open",
  "templateName":"My Template",
  "triggerDate":1234567,
  "dueDate":1234567,
  "attestation":false,
  "notes":"",
  "urls":[],
  "fileNames":[],
  "allowedFileTypes":[".pdf"],
  "intervalType":"years",
  "interval":1,
  "trigger":"invoice_paid",
  "advisor":{},
  "client":{}
}

Required Permissions

User must be Full-access Advisor or Admin.

HTTP Request

PUT /api/public/v1/deliverables/<ID>

URL Parameters

Parameter	Description
ID	The ID of the deliverable to update.

Arguments

Value	Required	Type	Description
advisorID	false	number	This will create the deliverable and advisor relationship. If this is not sent on the request, the existing advisor ID will be maintained.
clientID	false	number	This will create the deliverable and client relationship. If this is not sent on the request, the existing client ID will be maintained.
triggerDate	false	number	This is the unix timestamp used to calculate the date the deliverable is due. If this is not sent on the request, the existing trigger date will be maintained.

Response

The updated deliverable object, if the call succeeded. If the request failed, this call returns an error.

Submit a Deliverable

curl /api/public/v1/deliverables/2/submit \
     -H "Authorization: Bearer advicepay_api_key" \
     -d '{"description":"My description", "attestation":true, "notes":"My notes", "url":"https://www.advicepay.com", "fileNames":["file1.pdf","file2.pdf"]}' \
     -X PUT

import "net/http"

type submitDeliverableReq struct {
  Description string
  Attestation boolean
  Notes       string
  URL         string
  FileNames   []string
}

// Marshall request data to JSON string
data := submitDeliverableReq{
  Description:  "My description",
  Attestation:  true,
  Notes:        "My notes",
  URL:          "https://www.advicepay.com",
  FileNames:    []string{"file1.pdf", "file2.pdf"}
}
jsonData, err := json.Marshal(data)
// ...

// Build request
req, err := http.NewRequest("PUT", "/api/public/v1/deliverables/2/submit", bytes.NewBuffer(jsonData))
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "advisorID":1,
  "clientID":2,
  "engagementID":3,
  "status":"complete",
  "templateName":"My Template",
  "triggerDate":1234567,
  "dueDate":1234567,
  "notes":"My notes",
  "attestation":true,
  "urls":["https://www.advicepay.com"],
  "fileNames":["file1.pdf", "file2.pdf"],
  "allowedFileTypes":[".png",".jpg",".pdf",".docx"],
  "intervalType":"years",
  "interval":1,
  "trigger":"invoice_paid",
  "advisor":{},
  "client":{}
}

Required Permissions

User must be an Advisor or Admin.

HTTP Request

PUT /api/public/v1/deliverables/<ID>/submit

URL Parameters

Parameter	Description
ID	The ID of the deliverable to submit.

Arguments

Value	Required	Type	Description
description	false	string	This is the advisor-defined description of the deliverable. It should fill in any details missing from the title.
attestation	false	boolean	A boolean whether or not the advisor attests to "providing the agreed upon services to the client and the included evidence is accurate".
notes	false	string	These are the notes from the advisor.
url	false	string	This is the URL of the evidence provided by the advisor.
fileNames	false	string list	This is the collection of file names containing the evidence uploaded by the advisor.

Response

The updated deliverable object, if the call succeeded. If the request failed, this call returns an error.

Get the File Upload URL

AdvicePay uses pre-signed upload URLs that are only good for 5 minutes.

curl /api/public/v1/deliverables/2/upload_url?fileName=myfile.pdf \
     -H "Authorization: Bearer advicepay_api_key"

import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/deliverables/1/upload_url?fileName=myfile.pdf", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "uploadURL": "https://ap.s3.amazonaws.com/thepath/myfile.pdf"
}

Required Permissions

User must be an Advisor or Admin.

HTTP Request

GET /api/public/v1/deliverables/<ID>/upload_url

URL Parameters

Parameter	Description
ID	The ID of the deliverable to submit.

Arguments

Value	Required	Type	Description
fileName	true	string	This is the name of the file to be uploaded

Response

An object containing the upload URL, if the call succeeded. If the request failed, this call returns an error.

Deliverable File Download

curl /api/public/v1/deliverables/1/files/my%20file.pdf/download \
     -H "Authorization: Bearer advicepay_api_key"

import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/deliverables/1/files/my%20file.pdf/download?expect=json", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "data":"Base64-encoded Data Here",
}

Required Permissions

User must be an Advisor or Admin.

HTTP Request

GET /api/public/v1/deliverables/<ID>/files/<fileName>/download

URL Parameters

Parameter	Description
ID	The ID of the deliverable to submit.
fileName	The URL-encoded name of the file to be downloaded

Query Parameters

Parameter	Default	Type	Description
expect	binary	string	The expected response type. Must be one of "binary" (default) or "json".

Response

Returns the requested file. If "expect" query parameter is "binary" or omitted, the response will contain the binary representation of the file. The response header will have a "Content-Type" of "application/octet-stream" and "Content-Transfer-Encoding" of "binary". If "expect" query parameter is "json", the response will contain a file transfer object with a Base64-encoded representation of the file.

Get the File Download URL (deprecated in favor of deliverable file download)

AdvicePay uses pre-signed download URLs that are only good for 5 minutes.

curl /api/public/v1/deliverables/2/download_url?fileName=myfile.pdf \
     -H "Authorization: Bearer advicepay_api_key"

import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/deliverables/1/download_url?fileName=myfile.pdf", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "downloadURL": "https://ap.s3.amazonaws.com/thepath/myfile.pdf"
}

Required Permissions

User must be an Advisor or Admin.

HTTP Request

GET /api/public/v1/deliverables/<ID>/download_url

URL Parameters

Parameter	Description
ID	The ID of the deliverable to submit.

Arguments

Value	Required	Type	Description
fileName	true	string	This is the name of the file to be downloaded

Response

An object containing the download URL, if the call succeeded. If the request failed, this call returns an error.

Engagements

The Engagement Object

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "advisorID":1,
  "clientID":2,
  "externalID":"xyz123",
  "name":"Ongoing Engagement",
  "totalEngagementFee":2000,
  "advisor":{},
  "client":{},
  "agreements":[{}],
  "deliverables":[{}],
  "invoices":[{}],
  "subscriptions":[{}],
}

Attributes

Value	Type	Description
id	number	This is the engagement's unique indentifier, and should be stored to do any future queries for data belonging to that engagement.
createdAt	number	This is the unix timestamp for when the engagement was created.
updatedAt	number	This is the unix timestamp for when the engagement was updated.
deletedAt	number	This is the unix timestamp for when the engagement was deleted.
advisorID	number	This is the unique identifier of the advisor that the engagement was assigned to.
clientID	number	This is the unique identifier of the client that the engagement is associated with.
externalID	string	This is the external identifier for the engagement.
name	string	This is the name of the engagement.
totalEngagementFee	number	This is the total engagement fee (in cents) that is specified by an advisor when the chosen engagement workflow requires it.
advisor	object	The advisor on the engagement.
client	object	The client on the engagement.
agreements	object list	The agreements associated with the engagement (only visible in details view).
deliverables	object list	The deliverables associated with the engagement (only visible in details view).
invoices	object list	The invoices associated with the engagement (only visible in details view).
subscriptions	object list	The subscriptions associated with the engagement (only visible in details view).

The Engagement Revenue Object

{
  "engagementID":1,
  "projectedRevenue":1100,
  "totalEngagementFee":2000,
  "totalRevenue":100,
}

Attributes

Value	Type	Description
engagementID	number	This is the engagement's unique indentifier.
projectedRevenue	number	This is the revenue (in cents) that is projected to be collected in the future for the engagement.
totalEngagementFee	number	This is the total engagement fee (in cents) that is specified by an advisor when the chosen engagement workflow requires it.
totalRevenue	number	This is total revenue (in cents) that has already been collected for the engagement.

The Engagement Summary Object

{
  "id": 1,
  "createdAt": 1699922316,
  "updatedAt": 1701729256,
  "deletedAt": null,
  "advisorEmail": "example1@advicepay.com",
  "advisorExternalID": "Your_Advisor_External_ID",
  "advisorID": 1,
  "advisorName": "Bob Smith",
  "agreementIDs": [],
  "clientEmail": "example2@advicepay.com",
  "clientExternalID": "Your_Client_External_ID",
  "clientID": 2,
  "clientMetadata": {
    "My Dropdown": "Option 1"
  },
  "clientName": "Jim Jones",
  "deliverableIDs": [],
  "externalID": "",
  "invoiceIDs": [
      1,
      2,
  ],
  "name": "Standard Engagement",
  "officeID": 1,
  "primaryAgreementID": 1,
  "primaryAgreementName": "Financial Planning Agreement",
  "primaryAgreementStatus": "agreement_status_complete",
  "projectedRevenue": 120000,
  "subscriptionIDs": [
      1
  ],
  "totalEngagementFee": 150000,
  "totalRevenue": 40000
}

Attributes

Value	Type	Description
id	number	This is the engagement's unique indentifier.
createdAt	number	This is the unix timestamp for when the engagement was created.
updatedAt	number	This is the unix timestamp for when the engagement or any of the resources it contains were updated.
deletedAt	number	This is the unix timestamp for when the engagement was deleted.
advisorEmail	string	This is the advisor's email address.
advisorExternalID	string	This is the external ID of the advisor.
advisorID	number	This is the AdvicePay ID of the advisor.
advisorName	number	This is the full name of the advisor.
agreementIDs	number list	This is the list of IDs for all agreements on the engagement.
clientEmail	string	This is the client's email address.
clientExternalID	string	This is the external ID of the client.
clientID	string	This is the AdvicePay ID of the client.
clientMetadata	object	Any additonal information added to the client via a custom attribute will show here.
clientName	string	This is the full name of the client.
deliverableIDs	number list	This is the list of IDs for all deliverables on the engagement.
externalID	number	This is the external identifier for the engagement.
invoiceIDs	number list	This is the list of IDs of the invoices on the engagement.
name	string	This is the name of the engagement.
officeID	number	This is the ID of the engagement's office.
primaryAgreementID	number	This is the ID of the primary agreement on the engagement.
primaryAgreementName	string	This is the name of the template used to create the primary agreement.
primaryAgreementStatus	string	This is the status of the primary agreement. It will be one of: "agreement_status_created" (no action has been taken), "agreement_status_opened" (a signer has opened the document), "agreement_status_complete" (all signers have signed the document), "agreement_status_voided" (the signature request has been canceled), "agreement_status_draft" (the signature request needs to be completed before sending)
projectedRevenue	number	This is the revenue (in cents) that is projected to be collected in the future for the engagement.
subscriptionIDs	number list	This is the list of IDs of the subscriptions on the engagement.
totalEngagementFee	number	This is the total engagement fee (in cents) that is specified by an advisor when the chosen engagement workflow requires it.
totalRevenue	number	This is total revenue (in cents) that has already been collected for the engagement.

List Engagements

curl /api/public/v1/engagements?externalIDs[]=xyz123 \
     -H "Authorization: Bearer advicepay_api_key" \

import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/engagements?externalIDs[]=xyz123", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "items": [
    {
      "id":1,
      "createdAt":1551201267,
      "updatedAt":1551201267,
      "deletedAt":0,
      "advisorID":1,
      "clientID":2,
      "externalID":"xyz123",
      "name":"Ongoing Engagement",
      "advisor":{},
      "client":{},
    },
    ...
  ],
  "page":1,
  "perPage":10,
  "totalItems":100,
  "totalPages":10
}

HTTP Request

GET /api/public/v1/engagements

Query Parameters

Parameter	Default	Type	Description
page	1	number	This will determine which page to return.
perPage	10	number	This will determine the number of records to return (max is 100).
externalIDs	empty	string list	This will only return engagements with the specified external IDs.
advisorIDs	empty	string list	This will only return engagements for the specified advisors.
clientIDs	empty	string list	This will only return engagements for the specified clients.
createdAfter	empty	number	This is a unix timestamp to filter by createdAt.
createdBefore	empty	number	This is a unix timestamp to filter by createdAt.

Response

Returns a list of engagements sorted by created_at in descending order

Get an Engagement

curl /api/public/v1/engagements/1 \
     -H "Authorization: Bearer advicepay_api_key"

import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/engagements/1", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "advisorID":1,
  "clientID":2,
  "externalID":"xyz123",
  "name":"Ongoing Engagement",
  "advisor":{},
  "client":{},
  "agreements":[{}],
  "deliverables":[{}],
  "invoices":[{}],
  "subscriptions":[{}],
}

HTTP Request

GET /api/public/v1/engagements/<ID>

URL Parameters

Parameter	Description
ID	The ID of the engagement to fetch.

Response

Returns the requested engagement

Get Revenue for an Engagement

curl /api/public/v1/engagements/1/revenue \
     -H "Authorization: Bearer advicepay_api_key"

import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/engagements/1/revenue", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "engagementID":1,
  "projectedRevenue":1100,
  "totalRevenue":100
}

HTTP Request

GET /api/public/v1/engagements/<ID>/revenue

URL Parameters

Parameter	Description
ID	The ID of the engagement whose revenue to calculate.

Response

Returns the requested revenue for the engagement

Get Engagement Summaries

curl /api/public/v1/engagements/summary \
     -H "Authorization: Bearer advicepay_api_key" \

import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/engagements/summary", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "items": [
    {
      "id": 1,
      "createdAt": 1699922316,
      "updatedAt": 1701729256,
      "deletedAt": null,
      "advisorEmail": "example1@advicepay.com",
      "advisorExternalID": "Your_Advisor_External_ID",
      "advisorID": 1,
      "advisorName": "Bob Smith",
      "agreementIDs": [],
      "clientEmail": "example2@advicepay.com",
      "clientExternalID": "Your_Client_External_ID",
      "clientID": 2,
      "clientMetadata": {
        "My Dropdown": "Option 1"
      },
      "clientName": "Jim Jones",
      "deliverableIDs": [],
      "externalID": "",
      "invoiceIDs": [
          1,
          2,
      ],
      "name": "Standard Engagement",
      "officeID": 1,
      "primaryAgreementID": 1,
      "primaryAgreementName": "Financial Planning Agreement",
      "primaryAgreementStatus": "agreement_status_complete",
      "projectedRevenue": 120000,
      "subscriptionIDs": [
          1
      ],
      "totalEngagementFee": 150000,
      "totalRevenue": 40000
    },
    ...
  ],
  "page":1,
  "perPage":10,
  "totalItems":100,
  "totalPages":10
}

HTTP Request

GET /api/public/v1/engagements/summary

Query Parameters

Parameter	Default	Type	Description
page	1	number	This will determine which page to return.
perPage	10	number	This will determine the number of records to return (max is 100).
externalIDs	empty	string list	This will only return summaries for engagements with the specified external IDs.
advisorIDs	empty	string list	This will only return summaries for engagements for the specified advisors.
clientIDs	empty	string list	This will only return summaries for engagements for the specified clients.
createdAfter	empty	number	This is a unix timestamp to filter by the time the engagement was created.
createdBefore	empty	number	This is a unix timestamp to filter by the time the engagement was created.
updatedAfter	empty	number	This is a unix timestamp to filter by the time the engagement or any of its contained resources were last updated.

Response

Returns a list of engagement summaries sorted by created_at in descending order

Errors

AdvicePay uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, etc.). Codes in the 5xx range indicate an error with AdvicePay's servers (these are rare).

Some 4xx errors that could be handled programmatically (e.g., an email is not unique) include an error message that briefly explains the error reported.

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong or your permissions are not set.
404	Not Found -- The specified resource could not be found.
405	Method Not Allowed -- You tried to access an endpoint with an invalid method.
406	Not Acceptable -- You requested a format that isn't json.
409	Conflict -- likely that you are trying to create or update something with a non-unique email.
429	Too Many Requests -- Look at the following headers for more details: "X-RateLimit-Reset", "X-RateLimit-Remaining", and "X-RateLimit-Limit".
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Example Responses

{
  "code":409,
  "message":"Email example@advicepay.com is already in use",
  "details":null
}

{
  "code":400,
  "message":"permission: acceptable_advisor_permission",
  "details":{"Permission":"acceptable_advisor_permission"}
}

All error messages are returned with the following structure: {"code":409, "message":"example", "details":{"key":"value"}}.

Value	Description
code	This is the http status code.
message	This is the error message.
details	This is used to describe data validation issues in a map with the failed request value as the key and the validation rule that failed as the value.

Validation Messages

Message	Meaning
acceptable_invoice_status	Must be one of: "unpaid", "paid", "failed", "pending_payment", "pending_processing", "canceled", "refunded", "refund_failed", "pending_approval", or "approval_rejected".
acceptable_frequency	Must be one of: "Single Payment", "Monthly recurring", "Quarterly recurring", "Semi-Annual recurring", or "Annual recurring".
acceptable_advisor_permission	Must be one of: "Advisor", "Read-only Advisor", "No-login Advisor", or "Managed Advisor".
acceptable_user_permission	Must be one of: "Admin" or "Analyst".

Invoices

The Invoice Object

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "clientID":1,
  "advisorID":2,
  "engagementID": 3,
  "subscriptionID":1,
  "amount":1000,
  "description":"description",
  "invoiceDate":1551201267,
  "dueDate":1551201267,
  "failedAt":1551201267,
  "frequency":"Monthly recurring",
  "number":1001,
  "paidDate":1551201267,
  "paymentMethod":"ach",
  "refundAmount":0,
  "refundDate":0,
  "status":"paid",
  "splitRepCode":"HN15448",
  "advisor": {},
  "client": {},
  "serviceDescriptions": [],
  "payURL": "",
}

Attributes

Value	Type	Description
id	number	This is the invoice's unique indentifier.
createdAt	number	This is the unix timestamp for when the invoice was created in AdvicePay.
updatedAt	number	This is the unix timestamp for when the invoice was updated.
deletedAt	number	This is the unix timestamp for when the invoice was deleted.
clientID	number	This is the ID of the client that the invoice belongs to.
advisorID	number	This is ID of the advisor that the invoice belongs to.
engagementID	number	This is the ID of the engagement that the invoice belongs to.
subscriptionID	number	This is the ID of the subscription that invoice belongs to for recurring payments.
amount	number	This is amount of the invoice in cents.
description	string	This is the first description in the list of descriptions on the invoice that the advisor provided. Deprecated. Please see the serviceDescriptions attribute.
invoiceDate	number	This is the date in unix time that the invoice was sent to the client (set to 0 for upcoming invoices).
dueDate	number	This is due date in unix time for the invoice set by the advisor.
failedAt	number	This is the date in unix time when the charge failed (set to 0 if not failed).
frequency	string	This is frequency of the invoice. It will be one of: "Single Payment", "Monthly recurring", "Quarterly recurring", "Semi-Annual recurring", or "Annual recurring"
number	number	This is internal invoice number. Each advisor's invoice count starts att #1001.
paidDate	number	This is date in unix time that payment was made.
paymentMethod	string	This is the payment options given for the invoice. It will be one of: "ach", "ccd", or "either".
refundAmount	number	This is refund amount in cents if a refund has ocurreed on the invoice.
refundDate	number	This is refund date in unix time if a refund has ocurreed on the invoice.
status	string	This is status of the invoice. It will be one of: "unpaid" (no action has been taken), "paid" (invoice has been paid and funds have been transferred), "pending_payment" (user has submitted payment and money is transferring to bank account), "pending_processing" (user has submitted payment but subscription has not kicked off yet), "canceled", "refund_failed", "pending_approval", or "approval_rejected".
splitRepCode	string	This is split/rep code for the invoice that the advisor provided. This will be populated if the firm setting for split rep codes is set to Standard
advancedSplitRepCodes	object list	The list of advanced split rep codes. This will be populated if the firm setting for split rep coes is set to Advanced
advisor	object	The advisor on the invoice.
client	object	The client on the invoice.
serviceDescriptions	object list	The service descriptions on the invoice.
payURL	string	The URL were the invoice can be paid.

List Invoices

curl /api/public/v1/invoices \
     -H "Authorization: Bearer advicepay_api_key" \

import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/invoices", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "items": [
    {
      "id":1,
      "createdAt":1551201267,
      "updatedAt":1551201267,
      "deletedAt":0,
      "clientID":1,
      "advisorID":2,
      "engagementID": 3,
      "subscriptionID":1,
      "amount":1000,
      "description":"description",
      "invoiceDate":1551201267,
      "dueDate":1551201267,
      "failedAt":1551201267,
      "frequency":"Monthly recurring",
      "number":1001,
      "paidDate":1551201267,
      "paymentMethod":"ach",
      "refundAmount":0,
      "refundDate":0,
      "status":"paid",
      "splitRepCode":"HN15448",
      "advisor": {},
      "client": {},
      "payURL": "",
    },
    ...
  ],
  "page":1,
  "perPage":10,
  "totalItems":100,
  "totalPages":10
}

HTTP Request

GET /api/public/v1/invoices

Query Parameters

Parameter	Default	Type	Description
page	1	number	This will determine which page to return.
perPage	10	number	This will determine the number of records to return (max is 100).
status	empty	string	Filter by invoice status. Must be one of: "unpaid", "paid", "failed", "pending_payment", "pending_processing", "canceled", "refunded", "refund_failed", "pending_approval", or "approval_rejected".
frequency	empty	string	Filter by invoice frequency. Must be one of: "Single Payment", "Monthly recurring", "Quarterly recurring", "Semi-Annual recurring", or "Annual recurring".
paidAfter	empty	number	This is a unix timestamp to filter by paidDate.
paidBefore	empty	number	This is a unix timestamp to filter by paidDate.
advisorID	empty	number	Filter by invoice advisor.
clientID	empty	number	Filter by invoice client.
engagementID	empty	number	Filter by invoice engagement.
updatedAfter	empty	number	This is a unix timestamp to filter by updatedAt.
updatedBefore	empty	number	This is a unix timestamp to filter by updatedAt.

Response

Returns a list of invoices sorted by created_at in descending order

Get an Invoice

curl /api/public/v1/invoices/1 \
     -H "Authorization: Bearer advicepay_api_key"

import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/invoices/1", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "clientID":1,
  "advisorID":2,
  "engagementID": 3,
  "subscriptionID":1,
  "amount":1000,
  "description":"description",
  "invoiceDate":1551201267,
  "dueDate":1551201267,
  "failedAt":1551201267,
  "frequency":"Monthly recurring",
  "number":1001,
  "paidDate":1551201267,
  "paymentMethod":"ach",
  "refundAmount":0,
  "refundDate":0,
  "status":"paid",
  "splitRepCode":"",
  "advancedSplitRepCodes":[
    {
        "id":123,
        "createdAt":123456,
        "updatedAt":123456,
        "deletedAt":0,
        "advisorID":2,
        "percent":100,
        "advisor":{}
    }
  ]
  "advisor": {},
  "client": {},
  "payURL": "",
}

HTTP Request

GET /api/public/v1/invoices/<ID>

URL Parameters

Parameter	Description
ID	The ID of the invoice to fetch.

Response

Returns the requested invoice

Create an Invoice

curl /api/public/v1/invoices \
     -H "Authorization: Bearer advicepay_api_key" \
     -d '{"amount":1000, "dueDate":1551201267, "clientID":1, "serviceDescriptions":[{"title":"service one", "text":"description"}]}' \
     -X POST

import "net/http"

type serviceDescription struct {
  Title string
  Text  string
}

type createInvoiceReq struct {
  Amount              int
  DueDate             int64
  ClientID            uint
  ServiceDescriptions []serviceDescriptionsReq
}


// Marshall request data to JSON string
data := createInvoiceReq{
  Amount:              1000,
  DueDate:             1551201267,
  ClientID:            1,
  ServiceDescriptions: []serviceDescription{
    {Title: "service one", Text:"description"},
  },
}
jsonData, err := json.Marshal(data)
// ...

// Build request
req, err := http.NewRequest("POST", "/api/public/v1/invoices", bytes.NewBuffer(jsonData))
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "clientID":1,
  "advisorID":2,
  "engagementID": 3,
  "subscriptionID":0,
  "amount":1000,
  "description":"description",
  "dueDate":1551201267,
  "failedAt":0,
  "frequency":"Single Payment",
  "number":1001,
  "paidDate":0,
  "paymentMethod":"either",
  "refundAmount":0,
  "refundDate":0,
  "status":"unpaid",
  "splitRepCode":"",
  "advisor": {},
  "client": {},
  "payURL": "",
}

Required Permissions

User must be Managing Advisor, Full-Access Advisor or Admin.

HTTP Request

POST /api/public/v1/invoices

Arguments

Value	Required	Type	Description
amount	true	number	Number in cents, value must be greater than 50.
dueDate	true	number	This is due date in unix time. Must be a date in the future.
clientID	true	number	This is the AdvicePay ID of the client for which the invoice is intended.
serviceDescriptions	true	string	A list of service descriptions that will be displayed on the invoice.
advanceBilling	false	boolean	Default is false and will bill in arrears. If set to true, will bill ind advance.
externalEngagementID	false	string	Creating an invoice will create a new engagement. The engagement's external ID will be set to this value upon creation.
sendAsEmail	false	boolean	Default is false. If set to true, email with payment link will be sent to client.
emailMessage	false	string	Custom message to be included in the email sent to client.
paymentMethod	false	string	Default is "either". This is the payment options given for the invoice. Must be one of: "ach", "ccd", or "either".

Response

The newly created Invoice object, if the call succeeded. If the request failed, this call returns an error.

Download an Invoice PDF

curl -O -J /api/public/v1/invoices/1/download?expect=json \
     -H "Authorization: Bearer advicepay_api_key"

import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/invoices/1/download?expect=json", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "data":"Base64-encoded Data Here",
}

HTTP Request

GET /api/public/v1/invoices/<ID>/download

URL Parameters

Parameter	Description
ID	The ID of the invoice to download.

Query Parameters

Parameter	Default	Type	Description
expect	binary	string	The expected response type. Must be one of "binary" (default) or "json".

Response

Returns a PDF file for the invoice. If "expect" query parameter is "binary" or omitted, the response will contain the binary representation of the file. The response header will have a "Content-Type" of "application/octet-stream" and "Content-Transfer-Encoding" of "binary". If "expect" query parameter is "json", the response will contain a file transfer object with a Base64-encoded representation of the file.

Refund an Invoice

curl /api/public/v1/invoices/1/refund \
     -H "Authorization: Bearer <advicepay_api_key>" \
     -H "Content-Type: application/json" \
     -d '{"amount":"100000","customMessage":"Your refund is on the way"}'
     -X PUT

import (
  "net/http"
  "encoding/json"
)

// Build request
d := struct{
    Amount string `json:"amount"`
    CustomMessage string `json:"customMessage"`
}{
  Amount: 10000,
  CustomMessage:"Your refund is on the way",
}
jsonData, err := json.Marshal(d)
// ...
req, err := http.NewRequest("PUT", "/api/public/v1/invoices/1/refund", bytes.NewBuffer(jsonData))
req.Header.Add("Authorization", "Bearer <advicepay_api_key>")
req.Header.Add("Content-Type", "application/json")
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "clientID":1,
  "advisorID":2,
  "engagementID": 3,
  "subscriptionID":1,
  "amount":1000,
  "description":"description",
  "invoiceDate":1551201267,
  "dueDate":1551201267,
  "failedAt":0,
  "frequency":"Monthly recurring",
  "number":1001,
  "paidDate":1551201267,
  "paymentMethod":"ach",
  "refundAmount":0,
  "refundDate":1671201267,
  "status":"refunded",
  "splitRepCode":"",
  "advancedSplitRepCodes":[
    {
        "id":123,
        "createdAt":123456,
        "updatedAt":123456,
        "deletedAt":0,
        "advisorID":2,
        "percent":100,
        "advisor":{}
    }
  ]
  "advisor": {},
  "client": {},
  "serviceDescriptions": [],
  "payURL": "",
}

HTTP Request

PUT /api/public/v1/invoices/<ID>/refund

URL Parameters

Parameter	Description
ID	The ID of the invoice to refund.

Arguments

Value	Required	Type	Description
amount	true	number	Number in cents to refund, value must be greater than 50 and less than or equal to the invoice amount paid.
customMessage	false	string	If included, this will be included in the email notifying the client of the refund.

Response

Returns the refunded invoice

Notifications

The Notification Object

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "advisorID":1,
  "amount":0,
  "clientID":1,
  "invoiceID":1,
  "subscriptionID":0,
  "key":"invoice-failed",
  "text":"Invoice #1234 of $1.00 failed",
}

Attributes

Value	Type	Description
id	number	This is the notification's unique indentifier, and should be stored to do any future queries for data belonging to that notification.
createdAt	number	This is the unix timestamp for when the notification was created.
updatedAt	number	This is the unix timestamp for when the notification was updated.
deletedAt	number	This is the unix timestamp for when the notification was deleted.
advisorID	number	This is ID of the advisor that the notification belongs to.
amount	number	The amount (in cents) related to the notification (for money transfer notifications).
clientID	number	This is the ID of the client that the notification belongs to.
invoiceID	number	This is ID of the invoice associated with the notification (for invoice-specific notifications).
subscriptionID	number	This is the ID of the subscription associated with the notification (for subscription-specific notifications).
key	string	This is the key representing the type of the notification.
text	string	This is the text of the notification.

List Notifications

curl /api/public/v1/notifications \
     -H "Authorization: Bearer advicepay_api_key" \

import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/notifications", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "items": [
    {
      "id":1,
      "createdAt":1551201267,
      "updatedAt":1551201267,
      "deletedAt":0,
      "advisorID":1,
      "amount":0,
      "clientID":1,
      "invoiceID":1,
      "subscriptionID":0,
      "key":"invoice-failed",
      "text":"Invoice #1234 of $1.00 failed",
    },
    ...
  ],
  "page":1,
  "perPage":10,
  "totalItems":100,
  "totalPages":10
}

Required Permissions

User must be the Account Owner or an Admin/Analyst under the Account Owner.

HTTP Request

GET /api/public/v1/notifications

Query Parameters

Parameter	Default	Type	Description
page	1	number	This will determine which page to return.
perPage	10	number	This will determine the number of records to return (max is 100).
advisorID	empty	number	Filter by notification advisor.
clientID	empty	number	Filter by notification client.
createdAfter	empty	number	This is a unix timestamp to filter by createdAt.
createdBefore	empty	number	This is a unix timestamp to filter by createdAt.

Response

Returns a list of notifications sorted by created_at in descending order

Offices

Offices are only applicable to Enterprise accounts. Essential and Professional accounts have no concept of multiple Offices.

The Office Object

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "name":"Example Office"
}

Attributes

Value	Type	Description
id	number	This is the office's unique indentifier, and should be stored to do any future queries for data belonging to that office.
createdAt	number	This is the unix timestamp for when the office was created.
updatedAt	number	This is the unix timestamp for when the office was updated.
deletedAt	number	This is the unix timestamp for when the office was deleted.
name	string	The name of the office.

List Offices

curl /api/public/v1/offices \
     -H "Authorization: Bearer advicepay_api_key" \

import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/offices", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "items": [
    {
      "id":1,
      "createdAt":1551201267,
      "updatedAt":1551201267,
      "deletedAt":0,
      "name":"Example Office",
    },
    ...
  ],
  "page":1,
  "perPage":10,
  "totalItems":100,
  "totalPages":10
}

Required Permissions

User must be the Account Owner or an Admin/Analyst under the Account Owner.

HTTP Request

GET /api/public/v1/offices

Query Parameters

Parameter	Default	Type	Description
page	1	number	This will determine which page to return.
perPage	10	number	This will determine the number of records to return (max is 100).

Response

Returns a list of offices sorted by created_at in descending order

Get an Office

curl /api/public/v1/offices/1 \
     -H "Authorization: Bearer advicepay_api_key"

import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/offices/1", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "name":"Example Office",
}

Required Permissions

User must be the Account Owner or an Admin/Analyst under the Account Owner.

HTTP Request

GET /api/public/v1/offices/<ID>

URL Parameters

Parameter	Description
ID	The ID of the office to fetch.

Response

Returns the requested office

Create an Office

curl /api/public/v1/offices \
     -H "Authorization: Bearer advicepay_api_key" \
     -d '{"name":"Example Office"}' \
     -X POST

import "net/http"

type createOfficeReq struct {
    Name string `json:"name"`
}

// Marshall request data to JSON string
data := createOfficeReq{
  Name: "Example Office",
}
jsonData, err := json.Marshal(data)
// ...

// Build request
req, err := http.NewRequest("POST", "/api/public/v1/offices", bytes.NewBuffer(jsonData))
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "name":"Example Office",
}

Required Permissions

User must be the Account Owner or an Admin under the Account Owner.

HTTP Request

POST /api/public/v1/offices

Arguments

Value	Required	Type	Description
name	true	string	The name of the office. Trailing or leading whitespace will be trimmed.

Response

The newly created Office object, if the call succeeded. If the request failed, this call returns an error.

Update an Office

curl /api/public/v1/offices/1 \
     -H "Authorization: Bearer advicepay_api_key" \
     -d '{"name":"Updated Example Office"}' \
     -X PUT

import "net/http"

type updateOfficeReq struct {
    Name string `json:"name"`
}

// Marshall request data to JSON string
data := updateOfficeReq{
  Name: "Updated Example Office",
}
jsonData, err := json.Marshal(data)
// ...

// Build request
req, err := http.NewRequest("PUT", "/api/public/v1/offices/1", bytes.NewBuffer(jsonData))
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "name":"Updated Example Office",
}

Required Permissions

User must be the Account Owner or an Admin under the Account Owner.

HTTP Request

PUT /api/public/v1/offices/<ID>

URL Parameters

Parameter	Description
ID	The ID of the office to update.

Arguments

Value	Required	Type	Description
name	true	string	The new name of the office. Trailing or leading whitespace will be trimmed.

Response

The updated Office object, if the call succeeded. If the request failed, this call returns an error.

Other Objects

The Signer Object

{
  "agreementID":1,
  "email":"example@advicepay.com",
  "name":"first last",
  "status":"signer_status_complete",
  "signedAt":1551201267,
  "completedAt":1551201267,
  "signingOrder":0,
  "title":"Client",
  "externalID":"abc123",
}

Attributes

Value	Type	Description
agreementID	number	This is the unique indentifier of associated agreement.
email	string	This is the email of the signer.
name	string	This is the name of the signer.
status	string	This is status of the signature. It will be either an empty string "" or "signer_status_complete" when the signer has finished signing.
signedAt	number	This is a unix timestamp for when the signer signed. [DEPRECATED]
completedAt	number	This is a unix timestamp for when the signer has completed the agreement.
signingOrder	number	If signing order is enabled on the agreement this number represents the rank of the signer in the order.
title	string	This is the title of the signature role on the document.
externalID	string	This is the identifier from your system in the AdvicePay database. It will be an empty string "" if there is no externalID under the corresponding client or advisor object.

The eSign Template Object

{
    "name": "ExampleTemplate",
    "description": "Example eSign Template"
}

Attributes

Value	Type	Description
name	string	This is the name of the template.
description	string	This is the template's description.

The Service Description Object

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "invoiceID": 1,
  "title": "Monthly FP",
  "text": "Monthly financial planning services"
}

Attributes

Value	Type	Description
id	number	This is the service description's unique indentifier.
createdAt	number	This is the unix timestamp for when the service description was created.
updatedAt	number	This is the unix timestamp for when the service description was updated.
deletedAt	number	This is the unix timestamp for when the service description was deleted.
invoiceID	number	This is the ID of the invoice associated with the service description.
title	string	This is the short name to be displayed on the AdvicePay UI.
text	string	This is the text to be displayed on the invoice.

Create Service Description

Attributes

Value	Required	Type	Description
title	true	string	This is the short name to be displayed on the AdvicePay UI.
text	true	string	This is the text to be displayed on the invoice.

The Advanced Split Rep Code Object

{
  "advisorID": 108,
  "advisorExternalID": "abc123",
  "firstName": "Bob",
  "lastName": "Smith",
  "splitPercent": 100,
  "My custom attribute 1": "My custom attribute 1 value",
  "My custom attribute 2": "My custom attribute 2 value"
}

Attributes

Value	Type	Description
advisorID	number	This is the ID of the advisor associated with the advanced split rep code.
advisorExternalID	string	This is used to specify an identifier from your system in the AdvicePay database.
firstName	string	The advisor's first name
lastName	string	The advisor's last name
splitPercent	number	The percentage of the commission to be paid to the advisor.
metadata	string or string array	Any additonal advisor attributes selected to be displayed under advanced repcode settings.

The One Time Payment Invoice Object

Create One Time Payment Invoice

Attributes

Value	Required	Type	Description
amount	true	number	Number in cents, value must be greater than 50.
dueDate	true	number	This is due date in unix time. Must be a date in the future.
serviceDescriptions	true	object list	A list of service descriptions that will be displayed on the invoices.

The File Transfer Object

{
  "data":"Base64-encoded data here",
}

Attributes

Value	Type	Description
data	string	This Base64-encoded representation of a file

Pagination

{
  "items": [{},{},...],
  "page":1,
  "perPage":10,
  "totalItems":100,
  "totalPages":10
}

All top-level API resources have support for bulk fetches via "list" API methods. For instance, you can list invoices. Most list API methods share a common structure, taking these two parameters: page and perPage.

The structure if elements in items will change depending on the endpoint, but the rest of the payload structure will be the same.

Single Sign On

You will need to have your public certificate installed on an AdvicePay server before you are able to make SSO requests.

We've built a sandbox using our implementation so that it is easy to send test requests to localhost:<PORT>/auth/sso. You simply need to add your cert to a the project's root. There is no need to install go, unless you want to modify the library and build it yourself. Running the binary will start a server at localhost:<PORT>`. If you need access you can request it here.

Requesting Access

This endpoint creates a session using a link between a 3rd party system (identity provider) and AdvicePay (service provider). If AdvicePay has never seen the user before or the user was not created with a ssoID, they will need to login once to build the relationship between identity and service provider.

HTTP Request

POST /auth/sso

Query Parameters

Parameter	Required	Description
source	true	The company slug used to determine which certificate to validate against. AdvicePay will provide you with the source once we have you set up in our system.

Arguments

Value	Required	Type	Description
SAMLResponse	true	string	This is a base64 encoded string, and is often called the assertion.
RelayState	false	string	This can be passed as a relative URL to specify where the user gets redirected to after a successful SAML assertion.

Deep Linking

Many organizations require the ability to deep link into AdvicePay and this can be accomplished using the SSO RelayState. Deep linking is supported on any page within AdvicePay simply by setting the RelayState to /desiredPage. Below are some common examples.

Deep link to a client

RelayState

/clients/<ID>

Deep link to the payment request flow

RelayState

/payments/create

Optional Query Parameters

Parameter	Description
userID	This is the internal AdvicePay ID of the client to preselect.
externalUserID	This is the external ID that you have defined on the client to preselect.
externalEngagementID	The ID that you want to be populated on the engagement created by this payment request.
templateID	The AdvicePay ID of the eSign template to preselect.
splitRepCode	The split rep code to prepopulate. (not available if Advanced Split Rep Code is enabled in firm settings)

Subscriptions

The Subscription Object

{
  "id": 1,
  "createdAt": 1603399833,
  "updatedAt": 1603399833,
  "deletedAt": 0,
  "clientID": 2,
  "advisorID": 1,
  "engagementID": 3,
  "amount": 10000,
  "billingPeriods": 12,
  "frequency": "Monthly recurring",
  "dueDate": 1603951200,
  "status": "inactive",
  "resumeDate": 0,
  "billDate": 1603951200,
  "advisor": {},
  "client": {}
}

Attributes

Value	Type	Description
id	number	This is the subscription's unique indentifier.
createdAt	number	This is the unix timestamp for when the subscription was created in AdvicePay.
updatedAt	number	This is the unix timestamp for when the subscription was updated.
deletedAt	number	This is the unix timestamp for when the subscription was deleted.
clientID	number	This is the ID of the client that the subscription belongs to.
advisorID	number	This is ID of the advisor that the subscription belongs to.
engagementID	number	This is the ID of the engagement that the subscription belongs to.
amount	number	This is amount of the subscription in cents.
billingPeriods	number	This is the number of billing periods the subscription will bill.
billDate	number	This is the next date this subscription will be billed.
dueDate	number	This is due date in unix time for the subscription set by the advisor.
frequency	string	This is frequency of the subscription. It will be one of: "Single Payment", "Monthly recurring", "Quarterly recurring", "Semi-Annual recurring", or "Annual recurring"
resumeDate	number	This is the date billing will resume if it has been paused.
status	string	This is status of the subscription. It will be one of: "inactive" (no action has been taken), "canceled" (subscription has been canceled), "active" (subscription has been activated), "deleted_by_stripe", "paused", "completed" (subscriptions has completed all billing periods), "pending_approval", "approval_rejected".
advisor	object	The advisor on the subscription.
client	object	The client on the subscription.

List Subscriptions

curl /api/public/v1/subscriptions \
     -H "Authorization: Bearer advicepay_api_key" \

import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/subscriptions", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "items": [
    {
      "id": 1,
      "createdAt": 1603399833,
      "updatedAt": 1603399833,
      "deletedAt": 0,
      "clientID": 2,
      "advisorID": 1,
      "engagementID": 3,
      "amount": 10000,
      "billingPeriods": 12,
      "frequency": "Monthly recurring",
      "dueDate": 1603951200,
      "billDate": 1603951200,
      "resumeDate": 0,
      "status": "inactive",
      "advisor": {},
      "client": {}
    }
    ...
  ],
  "page":1,
  "perPage":10,
  "totalItems":100,
  "totalPages":10
}

HTTP Request

GET /api/public/v1/subscriptions

Query Parameters

Parameter	Default	Type	Description
page	1	number	This will determine which page to return.
perPage	10	number	This will determine the number of records to return (max is 100).
status	empty	string	Filter by subscription status. Must be one of: "inactive", "canceled", "active", "deleted_by_stripe", "paused", "completed", "pending_approval", "approval_rejected".
frequency	empty	string	Filter by subscription frequency. Must be one of: "Single Payment", "Monthly recurring", "Quarterly recurring", "Semi-Annual recurring", "Annual recurring".
advisorID	empty	number	Filter by subscription advisor.
clientID	empty	number	Filter by subscription client.
engagementID	empty	number	Filter by subscription engagement.

Response

Returns a list of subscriptions sorted by created_at in descending order

Get a Subscription

curl /api/public/v1/subscriptions/1 \
     -H "Authorization: Bearer advicepay_api_key"

import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/subscriptions/1", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "id": 1,
  "createdAt": 1603399833,
  "updatedAt": 1603399833,
  "deletedAt": 0,
  "clientID": 2,
  "advisorID": 1,
  "engagementID": 3,
  "amount": 10000,
  "billingPeriods": 12,
  "frequency": "Monthly recurring",
  "dueDate": 1603951200,
  "billDate": 1603951200,
  "resumeDate": 0,
  "status": "inactive",
  "advisor": {},
  "client": {}
}

HTTP Request

GET /api/public/v1/subscriptions/<ID>

URL Parameters

Parameter	Description
ID	The ID of the subscription to fetch.

Response

Returns the requested subscription

Create a Subscription

curl /api/public/v1/subscriptions \
     -H "Authorization: Bearer advicepay_api_key" \
     -d '{"amount":1000, "dueDate":1551201267, "clientID":1, "frequency":"Monthly recurring", "serviceDescriptions":[{"title":"service one", "text":"description"}]}' \
     -X POST

import "net/http"

type serviceDescription struct {
  Title string
  Text  string
}

type createSubscriptionReq struct {
  Amount              int
  DueDate             int64
  ClientID            uint
  Frequency           string 
  ServiceDescriptions []serviceDescriptionsReq
}


// Marshall request data to JSON string
data := createSubscriptionReq{
    Amount:              1000,
  DueDate:             1551201267,
  ClientID:            1,
  Frequency            "Monthly recurring", 
  ServiceDescriptions: []serviceDescription{
    {Title: "service one", Text:"description"},
  },
}
jsonData, err := json.Marshal(data)
// ...

// Build request
req, err := http.NewRequest("POST", "/api/public/v1/subscriptions", bytes.NewBuffer(jsonData))
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "id": 1,
  "createdAt": 1551201267,
  "updatedAt": 1551201267,
  "deletedAt": 0,
  "clientID": 1,
  "advisorID": 2,
  "engagementID": 3,
  "amount": 1000,
  "frequency": "Monthly recurring",
  "dueDate": 1551201267,
  "status": "inactive",
  "resumeDate": 0,
  "billDate": 1551201267,
  "advisor": {},
  "client": {}
}

Required Permissions

User must be Managing Advisor, Full-Access Advisor or Admin.

HTTP Request

POST /api/public/v1/subscriptions

Arguments

Value	Required	Type	Description
amount	true	number	Number in cents, value must be greater than 50.
dueDate	true	number	This is due date in unix time. Must be a date in the future.
clientID	true	number	This is the AdvicePay ID of the client for which the subscription is intended.
frequency	true	string	Subscription frequency. Must be one of: "Single Payment", "Monthly recurring", "Quarterly recurring", "Semi-Annual recurring", "Annual recurring".
serviceDescriptions	true	object list	A list of service descriptions that will be displayed on the invoices.
advanceBilling	false	boolean	Default is false and will bill in arrears. If set to true, will bill ind advance.
sendAsEmail	false	boolean	Default is false. If set to true, email with payment link will be sent to client.
emailMessage	false	string	Custom message to be included in the email sent to client.
paymentMethod	false	string	Default is "either". This is the payment options given for the subscription. Must be one of: "ach", "ccd", or "either".
billingPeriods	false	number	Sets the max billing periods the subscriptions will bill.
otpInvoice	false	object	An upfront one time payment to be charged when activating the subscription.

Response

The newly created Subscription object, if the call succeeded. If the request failed, this call returns an error.

Transfers

The transfers endpoint is currently only available to Enterprise accounts. Note: This endpoint is slow and may take over 10 seconds to return. Please adjust request timeouts accordingly. We highly recommend using the arrivalBefore and arrivalAfter parameters to limit the size of the responses.

The Transfer Object

{
  "id": "Kok1FeZg9HVyHl4ufXtHl6xBfOS",
  "status": "paid",
  "grossAmount": 1400,
  "bankDeposit": 1321,
  "arrivalDate": 1551201267,
  "paymentCount": 1,
  "feeOverride": 0,
  "transactions": [
    {
      "id": "1FK4P7HVyHl4ufXt73dCbyme",
      "transferID": "Kok1FeZg9HVyHl4ufXtHl6xBfOS",
      "transactionType": "charge",
      "paymentType": "CC",
      "grossAmount": 1400,
      "feeAP": 79,
      "feeOverride": 0,
      "total": 1321,
      "paidDate": 1551201267,
      "clientName": "first last",
      "clientExternalID": "",
      "advisorName": "first last",
      "advisorEmail": "example@advicepay.com",
      "advisorExternalID": "extIDa",
      "advisorID": 1,
      "agreementID": 1,
      "invoiceID": 1,
      "invoiceNum": 1001,
      "invoiceType": "Single Payment",
      "recurringStartDate": 0,
      "recurringEndDate": 0,
      "invoiceDescription": "first description",
      "serviceDescriptions": ["first description", "second description"],
      "splitRepCode": "",
      "advancedSplitRepCodes": [
        {
          "advisorExternalID": "extIDa",
          "advisorID": 1,
          "firstName": "first",
          "lastName": "last",
          "splitPercent": 50
        },
        {
          "advisorExternalID": "extIDb",
          "advisorID": 2,
          "firstName": "adv2first",
          "lastName": "adv2last",
          "splitPercent": 50
        }
      ],
    }
  ]
}

Attributes

Value	Type	Description
id	string	This is the transfer's unique indentifier.
status	string	This is status of the transfer. It will be one of: "paid" (funds have been successfully transferred), "pending" (waiting to be submitted to the bank), "in_transit" (submitted to the bank), "failed", "canceled".
grossAmount	number	This is the amount of the total transaction charges in cents.
bankDeposit	number	This is the amount for deposit in cents.
arrivalDate	number	This is the unix timestamp for arrival of deposit to bank account.
paymentCount	number	This is the number of transactions included in the transfer.
feeOverride	number	This is the calculated percentage firm fee amount. Percentage set under enterprise firm settings.
transactions	object list	This is the list of transactions included in the transfer.

The Transaction Object

Attributes

Value	Type	Description
id	string	This is the transaction's unique indentifier.
transferID	string	This is the ID of the transfer that the transaction belongs to.
transactionType	string	This is the type of the transaction. Typically one of: "charge", "payment", "refund", "payment_failure_refund", "check"
paymentType	string	This is the type of payment used for the transaction. It will be either "CC" (credit card), "ACH" (bank account), or "CHK" (check)
grossAmount	number	This is the amount chaged in cents.
feeAP	number	This is the amount of the transaction fee.
feeOverride	number	This is the calculated percentage firm fee amount. Percentage set under enterprise firm settings.
total	number	This is the amount for deposit in cents.
paidDate	number	This is the unix timestamp for when the charge was paid.
paymentMessage	string	This is the note that was written when the invoice was marked as paid.
clientName	string	This is the first and last name of the client.
clientExternalID	string	This is the optional id field on the client object.
advisorName	string	This is the first and last name of the advisor on the invoice.
advisorEmail	string	This is the email of the advisor on the invoice.
advisorExternalID	string	This is the optional id field on the advisor object.
advisorID	number	This is AdvicePay's unique internal advisor ID.
agreementID	number	This is AdvicePay's unique internal agreement ID.
engagementExternalID	string	This is the optional id field on the engagement object.
engagementID	number	This is AdvicePay's unique internal engagement ID.
invoiceID	number	This is AdvicePay's unique internal invoice ID.
invoiceNum	number	This is the invoice number shown on the invoice. Each advisor's invoice count starts at #1001.
invoiceType	string	This is the type of the invoice. It will be one of: "Single Payment", "Monthly recurring", "Quarterly recurring", "Semi-Annual recurring", or "Annual recurring"
recurringStartDate	number	This is the unix timestamp for when the the recurring payment was started.
recurringEndDate	number	This is the unix timestamp for when the the recurring payment ends.
invoiceDescription	string	This is the first description on the invoice (Deprecated in favor of serviceDescriptions attribute).
serviceDescriptions	string list	This is the array of descriptions on the invoice.
splitRepCode	string	This is split/rep code for the invoice that the advisor provided. This will be populated if the firm setting for split rep codes is set to Standard.
advancedSplitRepCodes	object list	The list of advanced split rep codes. This will be populated if the firm setting for split rep coes is set to Advanced.

List Transfers

Required Permissions

User must be Managing Advisor, Full-access Advisor or Admin.

curl /api/public/v1/transfers \
     -H "Authorization: Bearer advicepay_api_key" \

import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/transfers?arrivalAfter=1551201266&perPage=5", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

{
  "items": [
    {
      "id": "Kok1FeZg9HVyHl4ufXtHl6xBfOS",
      "status": "paid",
      "grossAmount": 1400,
      "bankDeposit": 1321,
      "arrivalDate": 1551201267,
      "paymentCount": 1,
      "feeOverride": 0,
      "transactions": [
        {
          "id": "1FK4P7HVyHl4ufXt73dCbyme",
          "transferID": "Kok1FeZg9HVyHl4ufXtHl6xBfOS",
          "transactionType": "charge",
          "paymentType": "CC",
          "grossAmount": 1400,
          "feeAP": 79,
          "feeOverride": 0,
          "total": 1321,
          "paidDate": 1551201267,
          "paymentMessage": "example message",
          "clientName": "first last",
          "clientExternalID": "",
          "advisorName": "first last",
          "advisorEmail": "example@advicepay.com",
          "advisorExternalID": "extIDa",
          "advisorID": 1,
          "agreementID": 1,
          "engagementID": 3,
          "engagementExternalID": "ABC123",
          "invoiceID": 1,
          "invoiceNum": 1001,
          "invoiceType": "Single Payment",
          "recurringStartDate": 0,
          "recurringEndDate": 0,
          "invoiceDescription": "first description",
          "serviceDescriptions": ["first description", "second description"],
          "splitRepCode": "",
          "advancedSplitRepCodes": [
            {
              "advisorExternalID": "extIDa",
              "advisorID": 1,
              "firstName": "first",
              "lastName": "last",
              "splitPercent": 50
            },
            {
              "advisorExternalID": "extIDb",
              "advisorID": 2,
              "firstName": "adv2first",
              "lastName": "adv2last",
              "splitPercent": 50
            }
          ]
        }
      ]
    },
    ...
  ],
  "perPage": 5,
  "hasMore": true
}

HTTP Request

GET /api/public/v1/transfers

Query Parameters

Parameter	Default	Type	Description
arrivalAfter	empty	number	This is a unix timestamp to filter for transfers with arrivalDate after this timestamp.
arrivalBefore	empty	number	This is a unix timestamp to filter for transfers with arrivalDate before this timestamp.

Response

Returns a list of transfers sorted by arrivalDate in descending order