Skip to main content
All CollectionsAPI Access
MetaPulse API v4
MetaPulse API v4

MetaPulse provides a simple API for you to list, read, create, update member and data.

Support avatar
Written by Support
Updated over 2 months ago

Domain Change

In Nov 2021 we changed our name from envisage to MetaPulse. The new domain is metapulse.com. Although the API will work on both metapulse.com and envisage.io, the latter is deprecated, therefore we recommend upgrading all API calls to metapulse.com

MetaPulse has a simple API that is available for your use, any feedback is welcome. 

This document represents version 4 of the API. You can find all versions listed in our help article: See all API Versions

You can use the API to programmatically list, read, create, update and destroy data points against your graphs and members.  For rate limits see MetaPulse API Usage Limits.
​
​

Sections:

  1. Setup

  2. Testing Authentication

  3. Using the Data Point API

  4. Using the Graphs API

  5. Using the Member Graphs API

  6. Using the Members API

  7. Using the Team Chart Post API

  8. Debugging

  9. Questions / Comments
    ​

Setup

_______________________________________
​

To begin, you will need the email you use to sign into MetaPulse along with the API key from your MetaPulse User Profile page.  

If you will be doing a lot of API calls, it is best practice to create an API user in MetaPulse and give this user profile the permissions needed to access the necessary graphs.  
​ 
While you can use your own email and API key, a dedicated API user account is recommended.

Back to Page Top
​

Testing Authentication

_______________________________________

The first test you should do is make sure you can authenticate with the server. MetaPulse uses header based authentication, so you need to set two headers in your request: API-EMAIL  and API-KEY . The email is your user email, the API key is from your profile page. 

You can check authentication is working by doing the following command using the curl system utility:

curl -i \
     -H "api-email: <API_EMAIL>" \
     -H "api-key: <API_KEY>" \
     https://metapulse.com/api/v4/authentication

Which should give you a 200 OK with an empty body looking something like:

HTTP/2 200 
date: Mon, 07 Jan 2019 02:35:35 GMT
content-type: text/html
...

This 200 OK means you have successfully connected to the server.
​

Back to Page Top

Using the Data Point API
_______________________________________

Available Data Point API actions:

  1. List All Data Points

  2. List All Data Points Using Timestamp

  3. Show a Data Point

  4. Create or Update a Data Point

  5. Split a Weekly Data Point Across Two Months

  6. Delete a Data Point

  7. Set Multiple Data Points at Once

  8. Data Point Options

  9. Increment a Data Point

Note all following date formats are YYYY-MM-DD 

You can find the Graph ID (token) on the graphs page under the Graph Info menu option.

List All Data Points

The following lists all data points for a single graph. Values are returned in order of oldest to most recent.

curl -i \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "api-email: <API_EMAIL>" \
     -H "api-key: <API_KEY>" \
     -X GET \
     https://metapulse.com/api/v4/data_points?graph_id=<GRAPH_TOKEN>

So for example, if your API_EMAIL  was user@example.com  and your API_KEY  was sdlexamplekfj  and you wanted the data points for a weekly graph with the week ending on Thursday which had the graph token gra2example3 then the full command would be:

curl -i \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "api-email: <API_EMAIL>" \
     -H "api-key: <API_KEY>" \
     -X GET \
     https://metapulse.com/api/v4/data_points?graph_id=gra2example3

Which would return a JSON array looking something like this:

[
  {
    "graphToken": "gra2example3",
    "majorEvent": false,
    "note": null,
    "periodEnd": "2018-11-9",
    "periodStart": "2018-11-15",
    "value": "2.0",
    "updaterEmail": "bob@example.com",
    "createdAt": "2018-11-16T09:14:54.133+10:00"
    "updatedAt": "2018-11-16T09:14:54.133+10:00"
  },
  {
    "graphToken": "gra2example3",
    "majorEvent": false,
    "note": "We launched the product this week!",
    "periodEnd": "2018-11-16",
    "periodStart": "2018-11-22",
    "value": "4.0",
    "updaterEmail": "bob@example.com",
    "createdAt": "2018-11-23T09:14:05.894+10:00",
    "updatedAt": "2018-11-23T09:14:05.894+10:00"
  },
  {
    "graphToken": "gra2example3",
    "majorEvent": false,
    "note": null,
    "periodEnd": "2018-11-23",
    "periodStart": "2018-11-29",
    "value": "5.0",
    "updaterEmail": "bob@example.com",
    "createdAt": "2018-11-30T09:14:23.276+10:00",
    "updatedAt": "2018-11-30T09:14:23.276+10:00"
  },
  ...
]

This will return up to 50 data points at a time. You can fetch the next set of results by passing the page  parameter. For example: /api/v4/data_points?page=2. You can also customize the number of results by passing per_page=100 up to 500 results per request.

Back to Page Top | Back to Section Top

List All Data Points Using Timestamp

You can use the following parameters to list data points for a specific period:

  • starts_after Returns data points where the period starts after the given date.

  • starts_on_or_after Returns data points where the period starts on or after the given date.

  • starts_before Returns data points where the period starts before the given date.

  • starts_on_or_before Returns data points where the period starts on or before the given date.

  • ends_after Returns data points where the period ends after the given date.

  • ends_on_or_after Returns data points where the period ends on or after the given date.

  • ends_before Returns data points where the period ends before the given date.

  • ends_on_or_before Returns data points where the period ends on or before the given date.

You can use it like this:

curl -i \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "api-email: <API_EMAIL>" \
     -H "api-key: <API_KEY>" \
     -X GET \

/api/v4/data_points?graph_id=<TOKEN>&starts_after=2023-01-01&ends_on_or_before=2023-02-01


You can pass created_after and updated_after passing a timestamp to only retrieve records that have been created or updated after the specified timestamp.

When updated_after or created_after is used the records are returned in order of news to oldest. 

curl -i \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "api-email: <API_EMAIL>" \
     -H "api-key: <API_KEY>" \
     -X GET \

https://metapulse.com/api/v4/data_points?graph_id=<TOKEN>&created_after=2023-01-01


/** Or Use updated_after **/
https://metapulse.com/api/v4/data_points?graph_id=<TOKEN>&updated_after=2023-01-01

Back to Page Top | Back to Section Top

Show a Data Point

To view details for a specific data point, pass the date into the path: 

curl -i \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "api-email: <API_EMAIL>" \
     -H "api-key: <API_KEY>" \
     -X GET \
     https://metapulse.com/api/v4/data_points/2018-11-28?graph_id=<TOKEN>

This would return the following response:

{
  "graphToken": "<GRAPH_TOKEN>",
  "majorEvent": false,
  "note": null,
  "periodEnd": "2018-11-28",
  "periodStart": "2018-11-28",
  "value": "12.0",
  "updaterEmail": "bob@example.com",
  "createdAt": "2018-11-30T09:14:23.276+10:00",
  "updatedAt": "2018-11-30T09:14:23.276+10:00"
}

Back to Page Top | Back to Section Top

Create or Update a Data Point

To set the value for a data point, run the following command: 

curl -i \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "api-email: <API_EMAIL>" \
     -H "api-key: <API_KEY>" \
     -X POST \
     -d '{"graph_id":"<GRAPH_TOKEN>","period":"2018-11-28","value":"15"}' \
     https://metapulse.com/api/v4/data_points/set

This would set the value on 28th of November, 2018 to equal 15, creating it if it does not exist or updating it if it does exist. This would respond with:

{
  "graphToken": "<GRAPH_TOKEN>",
  "majorEvent": false,
  "note": null,
  "periodEnd": "2018-11-28",
  "periodStart": "2018-11-28",
  "value": "15.0",
  "updaterEmail": "bob@example.com",
  "createdAt": "2018-11-30T09:14:23.276+10:00",
  "updatedAt": "2018-11-30T09:14:23.276+10:00"
}

If there is an error setting the data point, you will receive a 400 Bad Request with an error message.

{"error": {"message": "Graph is archived"}}

Back to Page Top | Back to Section Top

Split a Weekly Data Point Across Two Months

It is possible to split a data point into two values if you have a weekly graph and the period spans two months. One value is assigned to the first month and another to the second month.

curl -i \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "api-email: <API_EMAIL>" \
     -H "api-key: <API_KEY>" \
     -X POST \
     -d '{"graph_id":"<GRAPH_TOKEN>","period":"2018-11-02","earlier_split_value":"10","later_split_value":"5"}' \
     https://metapulse.com/api/v4/data_points/set

In this example the organization's week ends on a Friday. The data point period is for the 27th of October through the 2nd of November, 2018. The value 10 would be assigned to the October portion and 5 would be assigned to the November portion of the week.

Back to Page Top | Back to Section Top

Delete a Data Point

To delete a data point, pass an empty value.

curl -i \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "api-email: <API_EMAIL>" \
     -H "api-key: <API_KEY>" \
     -X POST \
     -d '{"graph_id":"<GRAPH_TOKEN>","period":"2018-11-28","value":""}' \
     https://metapulse.com/api/v4/data_points/set

That for example would remove the value on 28th of November, 2018.

Back to Page Top | Back to Section Top

Set Multiple Data Points at Once

You can set multiple data points in a single request by supplying an array of data point values. This will create the data point if it does not exist and update the value if it does exist. If you pass an empty value it will delete the data point.

NOTE: You need to have edit permission level for all graphs you are trying to update with set_multiple

curl -i \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "api-email: <API_EMAIL>" \
     -H "api-key: <API_KEY>" \
     -X POST \
     -d '{
           "data_points": [
              {"graph_id": "gra123","value": "14","period": "2018-11-28"},
              {"graph_id": "gra123","value": "","period": "2018-11-29"}
           ]
         }' \
     https://metapulse.com/api/v4/data_points/set_multiple


For example, this would set the value on 28th of November, 2018 to equal 14 and delete the data point on the 29th.
​
This would return the following output:

HTTP/2 200 
date: Mon, 07 Jan 2019 03:04:49 GMT
content-type: application/json
...

If you need to set multiple datapoints for the same date, pass the period separately in the same /api/v4/data_points/set_multiple request.

{
  "period": "2019-01-01",
  "data_points": [
    {"graph_id": "gra12345", "value": 1},
    {"graph_id": "gra34567", "value": 2, "note": "Some note"},
    {"graph_id": "gra56789", "value": 3, "period": "2019-02-01"}
  ]
}

Note the last data point has a period. This will override the initial period passed in. Any data points which don't have a period fall back to that global period.

Also, this behaves the same as the set action, so it will:

  • Create a data point if it doesn't exist

  • Update a data point if it already exists

  • Delete a data point if it exists and the given value is empty

Back to Page Top | Back to Section Top

Data Point Options

The following options can be passed in when setting a data point.

graph_id (required)

The Graph ID (token) the data point belongs to.

period (required)

The date the data point is on.

value

The decimal value assigned to the data point.

earlier_split_value

The first part of the value if it is a weekly period which covers two months.

later_split_value

The last part of the value if it is a weekly period which covers two months.

note

The note attached to the data point.

append_note

Extra content to add to an existing note.

major_event

Boolean true or false depending on if it is a major event.

skip_expected_value_check

Set to false if you want to return an error when the value is outside the expected range.

Back to Page Top | Back to Section Top

Increment a Data Point

You can increment a data point for the 28th of November, 2018 by 1, creating it if it does not exist and setting it to the value of 1 or updating it by 1 if it does. Passing in a note value will append it to the existing note (if any) joined with a new line.

To do this, you would run the following command: 

curl -i \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "api-email: <API_EMAIL>" \
     -H "api-key: <API_KEY>" \
     -X PATCH \
     -d '{"graph_id":"<GRAPH_TOKEN>","value":"1","note":"Second Note","period":"2018-11-28"}' \
     https://metapulse.com/api/v4/data_points/increment

Which would give you in response if the graph already had the value of 15 and note of "First Note":

{
  "graphToken": "<GRAPH_TOKEN>",
  "majorEvent": false,
  "note": "First Note\nSecond Note",
  "periodEnd": "2018-11-28",
  "periodStart": "2018-11-28",
  "value": "16.0",
  "updaterEmail": "bob@example.com",
  "createdAt": "2018-11-30T09:01:32.921+10:00"
  "updatedAt": "2018-11-30T09:14:23.276+10:00"
}

Note, passing a negative value will decrement the data point by the amount given.
​

Using the Graphs API 

_______________________________________

Available Graph API actions:

  1. Create a Graph

  2. Search for a list of Graphs

  3. Search for a list of Graphs Using Timestamp

  4. Set Custom Attributes on a Graph

  5. Update a Graph

  6. Delete a Graph

Create a Graph

POST /api/v4/graphs HTTP/1.1
Host: metapulse.com
Content-Type: application/json

{
  "organisation_token": "abc123",
  "graph": {
    "name": ,
    "graph_type": "weekly",
    "responsible_member_email": "name@email.com"
  }
}

The organisation_token is the same as the "Organization ID" found on the organization settings.

If you want to add additional graph attributes while creating a graph, here's the full list:

name

Name of the graph

description

You can add a description for the graph

graph_type (only when creating a graph)

daily, weekly, monthly, quarterly, yearly, comparison, calculated or concatenated

display_frequency

daily, weekly, monthly, quarterly or yearly

inverted

true or false

responsible_member_email

To assign the graph to a member, you need to provide the member's email address.

decimal_places

1, 2, 3, etc.

viability_line

true or false

unit_symbol

any symbol

unit_position

left or right. This will place the symbol on the left or right side of the value.

scale_minimum

You can set a minimum value for the graph. If there is a value outside of this scope, the scope will be ignored.

scale_maximum

You can set a maximum value for the graph. If there is a value outside of this scope, the scope will be ignored.

missing_data_treatment

gap, zero or hide

hidden

true or false

permission_level

none, view, add, edit or admin

show_values_on_graph

true or false

show_incomplete_values

true or false

aggregate_method

It determines how values are displayed at lower frequencies. For example, it can display all values in the period, the average of all values, the minimum / maximum value within the period, the first or last reported value of the period. The values are sum, average, minimum, maximum, first or last

data_collection_days

It's useful when daily graphs are used. It will collect data on all or specific days. The format is [false, true, true, true, true, true, false] in which a value is specified for each day. In the above example, it will collect data on Tuesday, Wednesday, Thursday, Friday and Saturday. Sunday and Monday are omitted because they are set to false.

connect_incomplete_period

true or false

Back to Page Top | Back to Section Top

Search for a list of Graphs

MetaPulse has a power search function in the Graphs Index API. 

Both graph names and user names can be searched.

The follow code returns all graphs with the term "Income" in the name.

Note, this also will returns any graph with an associated user that has the search term in their name.

curl -i \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "api-email: <API_EMAIL>" \
     -H "api-key: <API_KEY>" \
     -X GET \
     https://metapulse.com/api/v4/graphs?term=Income

Which should return 200 OK with an array of the graph tokens, names and graph type that match the search: 

[
  {
    "token": "grawrddq12o",
    "name": "Total Clients",
    "graphType": "weekly",
    "availableFrequencies": ["weekly", "monthly", "quarterly", "yearly"],
    "hidden": false,
    "archived": false,
    "responsibleMemberFullName": "Bob Smith",
    "responsibleMemberEmail": "bob@example.com",
    "responsibleMemberEmployeeId": "ABC123",
    "customAttributes": [{"name": "Internal ID", "value": "789"}]
  }, {
    "token": "gra8sd2qkez",
    "name": "Gross Income",
    "graphType": "daily",
    "availableFrequencies": ["daily", "weekly", "monthly", "quarterly", "yearly"],
    "hidden": false,
    "archived": false,
    "createdAt": "2018-11-30T09:01:32.921+10:00"
    "updatedAt": "2018-11-30T09:14:23.276+10:00"
    "responsibleMemberFullName": "Jane Smith",
    "responsibleMemberEmail": "jane@example.com",
    "responsibleMemberEmployeeId": "",
    "customAttributes": []
  }
]

The possible list of types returned for graphType are:

  • daily 

  • weekly  

  • monthly 

  • quarterly 

  • yearly 

  • calculated 

  • comparison 

  • concatenated 

This will return up to 50 graphs at a time. You can fetch the next set of results by passing the page parameter. For example: /api/v4/graphs?page=2. You can also customize the number of results by passing per_page=100 up to 500 results per request.

By default only active graphs are returned. Pass include_hidden=true to also return hidden graphs. Pass include_archived=true to also return archived graphs.

Back to Page Top | Back to Section Top

Search for a list of Graphs Using Timestamp

You can pass created_after and updated_after passing a timestamp to only retrieve records that have been created or updated after the specified timestamp.

When updated_after or created_after is used the records are returned in order of news to oldest. 

curl -i \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "api-email: <API_EMAIL>" \
     -H "api-key: <API_KEY>" \
     -X GET \
     "https://metapulse.com/api/v4/graphs?term=Income"

"https://metapulse.com/api/v4/graphs?term=Income&created_after=<TIMESTAMP>" 

/** Or Use updated_after **/
"https://metapulse.com/api/v4/graphs?term=Income&updated_after=<TIMESTAMP>"

Back to Page Top | Back to Section Top

Set Custom Attributes on a Graph

Custom attributes allow you to define your own metadata on a graph. You can set custom attributes on a graph by supplying a name and value:

curl -i \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "api-email: <API_EMAIL>" \
     -H "api-key: <API_KEY>" \
     -X POST \
     -d '{"graph_id": "grawrddq12o", "name": "Department", "value": "A17"}' \
     "https://metapulse.com/api/v4/graph_custom_attributes"

That example will either create or update the custom attribute "Department" on graph grawrddq12o. For setting a Date Range Type see Setting a Member Custom Attributes with type Date Range.

The graph details will be returned on success:

{
  "token": "grawrddq12o",
  "name": "Total Clients",
  "graphType": "weekly",
  "availableFrequencies": ["weekly", "monthly", "quarterly", "yearly"],
  "hidden": false,
  "archived": false,
  "createdAt": "2018-11-30T09:01:32.921+10:00"
  "updatedAt": "2018-11-30T09:14:23.276+10:00"
  "responsibleMemberFullName": "Bob Smith",
  "responsibleMemberEmail": "bob@example.com",
  "responsibleMemberEmployeeId": "ABC123",
  "customAttributes": [{"name": "Department", "value": "A17"}]
}

Back to Page Top | Back to Section Top

Update a Graph

Send a PATCH request to the https://metapulse.com/api/v4/graphs/GRAPH_ID URL to update the graph.

curl -i \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "api-email: <API_EMAIL>" \
     -H "api-key: <API_KEY>" \
     -X PATCH \
     -d '{"graph": {"name": "Updated Name", "responsible_member_email": "name@email.com"}}'
} \
     https://metapulse.com/api/v4/graphs/gra12345

This would change the graph name and responsible member assigned to the graph matching the ID gra12345.

Back to Page Top | Back to Section Top

Delete a Graph

Graphs can be deleted through the API. You need to pass a DELETE method to the https://metapulse.com/api/v4/graphs/[GRAPH_ID] URL. For example:

curl -i \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "api-email: <API_EMAIL>" \
     -H "api-key: <API_KEY>" \
     -X DELETE \
     https://metapulse.com/api/v4/graphs/[GRAPH_ID]

Back to Page Top | Back to Section Top

Using the Member Graphs API

_______________________________________

Available Member Graphs API actions:

  1. List all viewable Graphs for a Member

  2. List all editable Graphs for a Member

  3. List all responsible Graphs for a Member

  4. List all Graphs for a Member Using Timestamp

List all viewable Graphs for a Member 

To get a list of all graph tokens and the graph names viewable by a given user email, you can run the following command: 

export params="email=mikel@reinteractive.net&type=viewable"
curl -i \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "api-email: <API_EMAIL>" \
     -H "api-key: <API_KEY>" \
     -X GET \
     "https://metapulse.com/api/v4/member_graphs?${params}"

Which should return 200 OK with an array of the graph tokens, names and graph type that the user is able to edit: 

[
  {
    "token": "grawrddq12o",
    "name": "Total Clients",
    "graphType": "weekly",
    "hidden": false,
    "archived": false,
    "createdAt": "2018-10-12T11:21:13.209+10:00"
    "updatedAt": "2018-10-13T17:12:43.847+10:00"
    "responsibleMemberEmail": "bob@example.com",
    "responsibleMemberEmployeeId": ""
  }, {
    "token": "gra8sd2qkez",
    "name": "Gross Income",
    "graphType": "daily",
    "hidden": false,
    "archived": false,
    "createdAt": "2018-11-30T09:01:32.921+10:00"
    "updatedAt": "2018-11-30T09:14:23.276+10:00"
    "responsibleMemberEmail": "jane@example.com",
    "responsibleMemberEmployeeId": ""
  }
]

The possible list of types returned for graphType are:

  • daily 

  • weekly  

  • monthly 

  • quarterly 

  • yearly 

  • calculated 

  • comparison 

  • concatenated 

You can also specify the member using their Employee ID field if set:

export params="employee_id=ABC123&type=viewable"
curl -i \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "api-email: <API_EMAIL>" \
     -H "api-key: <API_KEY>" \
     -X GET \
     "https://metapulse.com/api/v4/member_graphs?${params}"

This will return up to 50 graphs at a time. You can fetch the next set of results by passing the page parameter. For example: /api/v4/member_graphs?page=2. You can also customize the number of results by passing per_page=100 up to 500 results per request.

Note, you can pass created_after and updated_after passing a timestamp to only retreive records that have been created or updated after the specified timestamp.

Back to Page Top | Back to Section Top

List all editable Graphs for a Member 

To get a list of all graph tokens and the graph names that the given member can edit, pass the type=editable parameter, for example: 

export params="email=mikel@reinteractive.net&type=editable"
curl -i \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "api-email: <API_EMAIL>" \
     -H "api-key: <API_KEY>" \
     -X GET \
     "https://metapulse.com/api/v4/member_graphs?${params}"

This will return the same output as listing the viewable graphs above.

Back to Page Top | Back to Section Top

List all responsible Graphs for a Member 

To get a list of all graph tokens and the graph names that the given member is responsible for, pass the type=responsible parameter, for example: 

export params="email=mikel@reinteractive.net&type=responsible"
curl -i \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "api-email: <API_EMAIL>" \
     -H "api-key: <API_KEY>" \
     -X GET \
     "https://metapulse.com/api/v4/member_graphs?${params}"

This will return the same output as listing the viewable graphs above.

Back to Page Top | Back to Section Top

List all Graphs for a Member Using Timestamp

You can pass created_after and updated_after passing a timestamp to only retrieve records that have been created or updated after the specified timestamp.

When updated_after or created_after is used the records are returned in order of news to oldest. 

export params="email=mikel@reinteractive.net&type=editable"
curl -i \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "api-email: <API_EMAIL>" \
     -H "api-key: <API_KEY>" \
     -X GET \
     "https://metapulse.com/api/v4/member_graphs?${params}"

"https://metapulse.com/api/v4/member_graphs&type=responsible&created_after=<TIMESTAMP>" 

/** Or Use updated_after **/
"https://metapulse.com/api/v4/member_graphs&type=responsible&updated_after=<TIMESTAMP>"

Back to Page Top | Back to Section Top

Using the Members API

_______________________________________

Available Member API actions:

  1. List members under an organization

  2. List members under another member

  3. Show a Specific Member

  4. Set Custom Attributes for a Member

  5. Setting a Member Custom Attributes with type Date Range

  6. Ability to update Member Status Options

  7. Show Away Periods

    1. Show Away Periods for a Member

    2. Show Away Periods for all Members

  8. Create a member

  9. Archive a member

  10. Unarchive a member

List members under an organization

You can fetch members for an organization using the following:

See Organisation ID to get the ORGANISATION_TOKEN .

export params="organisation_id=<ORGANISATION_TOKEN>"
curl -i \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "api-email: <API_EMAIL>" \
     -H "api-key: <API_KEY>" \
     -X GET \
     "https://metapulse.com/api/v4/members?{params}"

Example Request

# GET https://metapulse.com/api/v4/members?organisation_id=orgmvn0c5uy

This will return the following fields for each member:

{
        "id": "memqomqq6z1",
        "email": "sally@example.com",
        "fullName": "Sally Pink",
        "phoneNumber": "123-555-0003",
        "phoneExtension": "",
        "mobileNumber": "",
        "employeeId": "A0003",
        "status": "Trial",
        "hireDate": "2019-02-02",
        "avatar": "https://assets.metapulse.com/uploads/member/avatar/16060/1719408423-836563322617575-0001-6684/avatar.png",
        "avatarMedium": "https://assets.metapulse.com/uploads/member/avatar/16060/medium_1719408423-836563322617575-0001-6684/avatar.png",
        "avatarSmall": "https://assets.metapulse.com/uploads/member/avatar/16060/small_1719408423-836563322617575-0001-6684/avatar.png",
        "avatarThumb": "https://assets.metapulse.com/uploads/member/avatar/16060/thumb_1719408423-836563322617575-0001-6684/avatar.png",
        "countryCode": "US",
        "countryName": "United States of America",
        "state": "Florida",
        "city": "",
        "building": "",
        "floorName": "",
        "floorSection": "",
        "timeZone": "Eastern Time (US & Canada)",
        "postId": "posurbkzjl7",
        "postName": "Printing Manager",
        "positionId": "posurbkzjl7",
        "positionName": "Printing Manager",
        "orgNodeName": "Printing",
        "managerEmail": "john.doe@email.com",
        "createdAt": "2022-09-14T20:27:12.054Z",
        "updatedAt": "2024-08-27T16:31:54.856Z",
        "ancestryPath": [
            {
                "id": "univ2fjlkxm",
                "name": "CEO & Founder",
                "post": "2.",
                "position": "2."
            },
            {
                "id": "unitdbbq2zq",
                "name": "Printing",
                "post": "2.E.",
                "position": "2.E."
            }
        ],
        "customAttributes": [
            {
                "name": "Eligible for Bonuses",
                "type": "boolean",
                "value": ""
            },
            {
                "name": "Type of Employee",
                "type": "text",
                "value": "Full Time"
            },
            {
                "name": "Cost Center",
                "type": "text",
                "value": ""
            },
            {
                "name": "New member arrival",
                "type": "date",
                "value": ""
            }
        ]
    },

This will return up to 50 members at a time. You can fetch the next set of results by passing the page  parameter. For example: /api/v4/members?page=2. You can also customize the number of results by passing per_page=100 up to 500 results per request.

Note, you can pass created_after and updated_after passing a timestamp to only retreive records that have been created or updated after the specified timestamp.

The Ancestry Path will return a JSON array of all positions from the top of their organization chart all the way down to the member's highest position. This provides a way to determine what area each member is in.

Back to Page Top | Back to Section Top

List members under another member

It's possible to fetch members overseen by another member by passing the overseen_by parameter.

export params="organisation_id=<ORGANISATION_TOKEN>&overseen_by=<EMAIL>"
curl -i \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "api-email: <API_EMAIL>" \
     -H "api-key: <API_KEY>" \
     -X GET \
     "https://metapulse.com/api/v4/members?{params}"

Example Request

# GET https://metapulse.com/api/v4/members?organisation_id=orgmvn3c2mz&overseen_by=ruth@example.com

Example Response

[
    {
        "id": "mem6ue5h4qr",
        "email": "jane@example.com",
        "fullName": "Jane Smith",
        "phoneNumber": "123-555-0000",
        "phoneExtension": "999",
        "mobileNumber": "123-555-1111",
        "employeeId": "A0001",
        "status": "",
        "hireDate": "2019-01-31",
        "avatar": null,
        "avatarMedium": null,
        "avatarSmall": null,
        "avatarThumb": null,
        "countryCode": "US",
        "countryName": "United States of America",
        "state": "",
        "city": "",
        "building": "",
        "floorName": "",
        "floorSection": "",
        "timeZone": "Eastern Time (US & Canada)",
        "postId": "posok6evrkz",
        "postName": "Administrator",
        "positionId": "posok6evrkz",
        "positionName": "Administrator",
        "orgNodeName": "Personnel Section",
        "managerEmail": "ruth@example.com",
        "createdAt": "2023-03-06T17:16:03.097Z",
        "updatedAt": "2024-07-04T16:38:29.261Z",
        "ancestryPath": [
            {
                "id": "uni93tli15w",
                "name": "Champion Printing",
                "post": "1.",
                "position": "1."
            },
            {
                "id": "unizoherqkp",
                "name": "Human Resources",
                "post": "1.B.",
                "position": "1.B."
            },
            {
                "id": "unixvzd0dsl",
                "name": "Personnel Section",
                "post": "1.B.1.",
                "position": "1.B.1."
            }
        ],
        "customAttributes": [
            {
                "name": "Type of Employee",
                "type": "text",
                "value": "Full Time"
            },
            {
                "name": "New member arrival",
                "type": "date",
                "value": ""
            },
            {
                "name": "Eligible for Bonuses",
                "type": "boolean",
                "value": ""
            }
        ]
    },
    {
        "id": "memqzsdu36w",
        "email": "joan@example.com",
        "fullName": "Joan Long",
        "phoneNumber": "123-555-0020",
        "phoneExtension": "",
        "mobileNumber": "",
        "employeeId": "A0020",
        "status": "",
        "hireDate": "2019-02-19",
        "avatar": "https://assets.metapulse.com/uploads/member/avatar/17832/1720111064-105892632149305-0003-7620/avatar.png",
        "avatarMedium": "https://assets.metapulse.com/uploads/member/avatar/17832/medium_1720111064-105892632149305-0003-7620/avatar.png",
        "avatarSmall": "https://assets.metapulse.com/uploads/member/avatar/17832/small_1720111064-105892632149305-0003-7620/avatar.png",
        "avatarThumb": "https://assets.metapulse.com/uploads/member/avatar/17832/thumb_1720111064-105892632149305-0003-7620/avatar.png",
        "countryCode": "US",
        "countryName": "United States of America",
        "state": "",
        "city": "",
        "building": "",
        "floorName": "",
        "floorSection": "",
        "timeZone": "Eastern Time (US & Canada)",
        "postId": "posfx8yluup",
        "postName": "Trainee",
        "positionId": "posfx8yluup",
        "positionName": "Trainee",
        "orgNodeName": "Personnel Section",
        "managerEmail": "ruth@example.com",
        "createdAt": "2023-03-06T17:16:05.510Z",
        "updatedAt": "2024-08-09T20:32:48.707Z",
        "ancestryPath": [
            {
                "id": "uni93tli15w",
                "name": "Champion Printing",
                "post": "1.",
                "position": "1."
            },
            {
                "id": "unizoherqkp",
                "name": "Human Resources",
                "post": "1.B.",
                "position": "1.B."
            },
            {
                "id": "unixvzd0dsl",
                "name": "Personnel Section",
                "post": "1.B.1.",
                "position": "1.B.1."
            }
        ],
        "customAttributes": [
            {
                "name": "Type of Employee",
                "type": "text",
                "value": "Full Time"
            },
            {
                "name": "New member arrival",
                "type": "date",
                "value": ""
            },
            {
                "name": "Eligible for Bonuses",
                "type": "boolean",
                "value": ""
            }
        ]
    }
]

This will return a list of members which are under that given member in the Team Chart.

Back to Page Top | Back to Section Top
​

Show a Specific Member

After you get the Member ID from the List action, or from the Manage Member Page, you can request details for an individual member as follows:

export email="<API_EMAIL>"
export key="<API_KEY>"
export memberid="<MEMBER_ID>" # eg, memaqt2owd7
export params="organisation_id=<ORGANISATION_TOKEN>"

curl -i \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "api-email: ${email}" \
     -H "api-key: ${key}" \
     -X GET \
     "https://metapulse.com/api/v4/members/{memberid}?{params}"

Example Request

# GET https://metapulse.com/api/v4/members/mem3p3rlk8f?organisation_id=orgmvn0c5uy

Which will return the same attributes for the individual member as is given in the list all members response.

Back to Page Top | Back to Section Top

Set Custom Attributes for a Member

Using the Member ID (mem12345678) obtains via List action above, or from the Manage Member Page you can update the member's Custom Attributes as follows:

curl -i \      
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \ 
     -H "api-email: <API_EMAIL>" \ 
     -H "api-key: <API_KEY>" \ 
     -X POST \ 
     -d '{"name": "Department", "value": "A17"}' \
   "https://metapulse.com/api/v4/members/<MEMBER_ID>/custom_attributes"

Back to Page Top | Back to Section Top

Setting a Member Custom Attributes with type Date Range

Here's syntax for setting a Date Range:

 curl -i \      
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \ 
     -H "api-email: <API_EMAIL>" \ 
     -H "api-key: <API_KEY>" \ 
     -X POST \ 
     -d '{"name": "On Leave", "value": {"start_date":"2022-01-01","end_date":"2022-02-13"}}' \
   "https://metapulse.com/api/v4/members/<MEMBER_ID>/custom_attributes"

Back to Page Top | Back to Section Top


Ability to update Member Status Options

Example request:

PATCH https://metapulse.com/api/v4/members/<MEMBER_ID>
{
  "member": {
    "status": "Contractor"
  }
}

The <MEMBER_ID> is the member token such as mem12345

You can pass any of these attributes to update the member.

  • email

  • employee_id

  • employee_type

  • status

  • hire_date

  • full_name

  • phone_number

  • phone_extension

  • mobile_number

  • country_code

  • state

  • city

  • building

  • floor_name

  • floor_section

  • time_zone

  • remove_avatar (boolean, true to remove)

  • notification_email_frequency (can be never, immediately, hourly, daily, weekly)

  • slack_user_id (if slack integration is enabled on account)

  • allow_saml (if SAML is enabled on account and it's the user's only account)

  • restrict_to_account_id (if it's the user's only account)

If the update is successful, the response will be 200 with the member details (same as GET member). If there's a validation error the response will be 400 error code with JSON body. Here's an example:

{
  "errors": {
    "message": "Unable to save member due to the following error: Email is invalid"
  }
}

Back to Page Top | Back to Section Top

Show Away Periods

Show Away Periods for a Member

List

Returns array of away periods for a given member.

Example Request

# GET https://metapulse.com/api/v4/member/[MEMBER_ID]/away_periods

Example Response

[
 { 
   "id": "e1957d54-bf87-4d1a-8aa1-d71d0563ddae",
   "startDate": "2022-01-01",
   "endDate": "2022-02-02",
   "reason": "Holiday"
 }
]

Show

Returns data for a single away period given an ID. Note the ID is in the URL.

Example Request

# GET https://metapulse.com/api/v4/member/[MEMBER_ID]/away_periods/[AWAY_PERIOD_ID]

Example Response

{ 
  "id": "e1957d54-bf87-4d1a-8aa1-d71d0563ddae",
  "startDate": "2022-01-01",
  "endDate": "2022-02-02",
  "reason": "Holiday",
}

Create

Creates an away period given attributes.

Example Request

# POST https://metapulse.com/api/v4/member/[MEMBER_ID]/away_periods
{ 
  "away_period": {
    "start_date": "2022-01-01",
    "end_date": "2022-02-02",
    "reason": "Holiday"
  }
}

Example Success Response

Same as "Show" above

Example Failure Response

# Returns 400 bad request
{"error":{"message":"Unable to save away period: Start Date can't be blank."}}

Update

Updates an away period given id and attributes.

Example Request

# PATCH https://metapulse.com/api/v4/member/[MEMBER_ID]/away_periods/[AWAY_PERIOD_ID]
{
  "away_period": {
    "start_date": "2022-01-01",
    "end_date": "2022-02-02",
    "reason": "Holiday"
  }
}

Example Success Response

Same as "Show" above

Example Failure Response

Same as "Create" above

Destroy

Deletes an away period given id.

Example Request

# DELETE https://metapulse.com/api/v4/member/[MEMBER_ID]/away_periods/[AWAY_PERIOD_ID]

Example Response

Nothing (200 OK)

Back to Page Top | Back to Section Top

Show Away Periods for all Members

List

Returns all away periods for a given organization.

Example Request

# GET https://metapulse.com/api/v4/members/away_periods/?organisation_id=[ORGANIZATION_ID]

Example Response

[
    {
        "id": "07e48750-b935-4e34-a24f-81b36bd830bb",
        "startDate": "2022-10-10",
        "endDate": "2022-10-15",
        "reason": "Vacation",
        "memberId": "memqomqq6z1",
        "memberEmail": "sally@example.com"
    },
    {
        "id": "bc6dfde0-ae30-4f69-84f1-d8c15654689a",
        "startDate": "2024-06-15",
        "endDate": "2024-06-21",
        "reason": "Vacation",
        "memberId": "mem1x1843ct",
        "memberEmail": "bill@example.com"
    },
    {
        "id": "fac08ea7-b927-470e-849c-aa02ecdf88f3",
        "startDate": "2024-08-12",
        "endDate": "2024-08-22",
        "reason": "Vacation",
        "memberId": "mem1st9w5wz",
        "memberEmail": "kim@example.com"
    }
]

If there are too many, you can split them in pages. The limit per page is 500.

Example Request

# GET https://metapulse.com/api/v4/members/away_periods?page=2&per_page=500

Back to Page Top | Back to Section Top

Create a member

Example Request

# POST https://metapulse.com/api/v4/members/
{
  "organisation_id": "orgt5omjbsk",
  "member": {
    "email": "bobcat@example.com",
    "full_name": "Bob Cat"
  }
}

Example Response

{
    "id": "mem2drlgc88",
    "email": "bobcat@example.com",
    "fullName": "Bob Cat",
    "phoneNumber": null,
    "phoneExtension": null,
    "mobileNumber": null,
    "employeeId": null,
    "status": null,
    "hireDate": null,
    "avatar": null,
    "avatarMedium": null,
    "avatarSmall": null,
    "avatarThumb": null,
    "countryCode": null,
    "countryName": null,
    "state": null,
    "city": null,
    "building": null,
    "floorName": null,
    "floorSection": null,
    "timeZone": "Sydney",
    "postId": null,
    "postName": null,
    "positionId": null,
    "positionName": null,
    "orgNodeName": null,
    "managerEmail": null,
    "createdAt": "2024-08-23T17:08:35.613Z",
    "updatedAt": "2024-08-23T17:08:35.613Z",
    "customAttributes": []
}

Back to Page Top | Back to Section Top

Archive a member

Example Request

# POST https://metapulse.com/api/v4/members/<MEMBER_ID>/archive

This will return an empty 200 OK response.

Back to Page Top | Back to Section Top

Unarchive a member

Example Request

# POST https://metapulse.com/api/v4/members/<MEMBER_ID>/unarchive

This will return an empty 200 OK response.

Back to Page Top | Back to Section Top

Using the Team Chart Position API

Available Position API actions:

  1. Set Custom Attributes for a Position

Set Custom Attributes for a Position

Using the position ID obtained from the Members List above or via Team Chart Data Export, you can update the position's Custom Attributes as follows:

curl -i \      
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \ 
     -H "api-email: <API_EMAIL>" \ 
     -H "api-key: <API_KEY>" \ 
     -X POST \ 
     -d '{"name": "Department", "value": "A17"}' \
"https://metapulse.com/api/v4/posts/<POST_ID>/custom_attributes"

For setting a Date Range Type see Setting a Member Custom Attributes with type Date Range.

Back to Page Top | Back to Section Top

Debugging

_______________________________________
​

Getting APIs to work can be a real pain sometimes, especially if you don't have direct access to send requests out.
​
A good tool to figure out if you are sending the API request correctly is beeceptor.com which is a free service to show you what your application is actually sending to MetaPulse.

Debugging

curl -i -H "api-key: API_KEY" \
        -H "api-email: bob@example.com" \
     https://test-metapulse.free.beeceptor.com/authentication

After sending this you'll get something back like:

HTTP/1.1 200 OK
Date: Tue, 05 Feb 2019 12:23:29 GMT
Content-Type: text/plain
Transfer-Encoding: chunked
Connection: keep-alive
Access-Control-Allow-Origin: *
Vary: Accept-Encoding


Hey ya! Great to see you here. Btw, nothing is configured for this request path. Create a rule and start building a mock API.

Which shows you BeeCeptor got your message.

Going to https://app.beeceptor.com/console/test-metapulse will then show you a request, which you can click and then view the headers of and see something like:

Which looks good!
​ 
​

Questions / Comments

_______________________________________

If you have any questions or comments, please contact us via support.

Did this answer your question?