API
Overview
We make available an API to enable you to programmatically create, retrieve, update and delete your networks and employee data within Polinode. API access is available to all users with a Polinode account.
In order to access the API you will need to generate an API credential from within the Polinode web application. This produces a Bearer token which you should treat like a password and store securely. Polinode does not store your token so be sure to record it prior to closing the dialogue. You can create multiple credentials and can delete (revoke) a credential at any time.
Enterprise organizations can also create organization-owned API credentials with fine-grained access scopes — see Scopes below.
The documentation on this page relates to version 2 of the Polinode API.
You will find a set of example API calls authored in Python here and in node.js here.
Authentication
The Polinode API uses bearer-token authentication. Supply your token in an Authorization header on every request:
Authorization: Bearer <your-token>
Bearer tokens are only secure if used over an HTTPS connection so it is important that you always specify https://app.polinode.com/api/v2 as your base route.
LEGACY BASIC AUTH
Older credentials use HTTP Basic Access Authentication, with the Public Key supplied as the username and the Private Key as the password. This scheme is deprecated but existing Basic Auth credentials continue to work. New credentials are bearer tokens.
Scopes
Each API credential carries a set of scopes that determine which resources it can access and whether it can read, write or both. A request that targets a resource the credential is not scoped for is rejected with a 403.
Scopes are expressed as <resource>:<action>, where action is read or write:
| Resource | Read scope | Write scope |
|---|---|---|
| Networks | networks:read | networks:write |
| Metrics | metrics:read | metrics:write |
| Employees | employees:read | employees:write |
| Custom Fields | customFields:read | customFields:write |
| Survey Responses | responses:read | responses:write |
| Surveys | surveys:read | surveys:write |
Key points:
- Read and write are independent. A credential with only a write scope can create/update/delete but cannot read, and a read-only credential cannot perform any mutating call. Holding
readdoes not grantwriteand vice versa. - Method determines the action. Safe requests (
GET) require thereadscope; mutating requests (POST,PUT,PATCH,DELETE) require thewritescope. - A Full API access credential is granted read and write across all of the resources above.
- Embedding (
embed:manage) is the scope for Embedding: it lets an organization credential provision managed users and create embedded sessions. Full API access credentials include it; a credential with custom scopes needs it selected.
If a call fails with a 403 and you expected it to succeed, check that the credential includes the required <resource>:<action> scope. You can view a credential's exact scopes via the View access details action on the API Credentials screen.
Compression
The Polinode API supports compression of HTTP body objects. NetworkJSON for large networks can be large and compressing the HTTP body using gzip for example can reduce the upload size by a factor of ~10x. To use compression please be sure to include the appropriate Content-Encoding header with your request, e.g. 'Content-Encoding': 'deflate'.
Base Route
The base route for the Polinode API is https://app.polinode.com/api/v2. It is to this route that you will add the routes detailed below. For example to GET a particular network you would use https://app.polinode.com/api/v2/networks/555194b407e3712f1beb966f where 555194b407e3712f1beb966f is the id of the network you are fetching.
Networks API
GET /networks
Retrieve all networks for the user.
Parameters:
None
Response on Success:
An array of all the user’s networks is returned with each element containing a network as per Format for Networks but excluding networkJSON.
GET /networks/:id
Retrieve a specific network.
URL Parameters:
| Name | Type | Description |
|---|---|---|
| id* | String | The network id. Required. |
| *=required. |
Response on Success:
See Format for Networks.
POST /networks
Create a new network.
Body Parameters:
See Format for Networks. Body parameters must include required keys and should not include internal keys.
In addition, organization-owned credentials accept an optional owner parameter:
| Name | Level | Type | Description |
|---|---|---|---|
| owner | 1 | String | The user who should own the created network, given as either their email address or their user id. Organization-owned credentials only; ignored for user-owned credentials. |
Every network is owned by a user, and that owner's account is where the network appears in the web application. A user-owned credential always creates networks owned by the user the credential belongs to.
An organization-owned credential is not tied to a single person, so it decides the owner as follows:
- If
owneris supplied, it must name a member of the credential's own organization. Members outside the organization, unknown addresses, unverified or suspended accounts, and Access-only members cannot be named; all of these return a400. - If
owneris omitted, the network is owned by the user who created the credential.
If the credential's creator can no longer own networks — for example they have left the organization — a create without owner returns a 400 asking you to supply one.
The resolved owner's own plan limits apply. If they have already reached their maximum number of public or private networks the call returns a 403 naming that user, even though the request was made with an organization credential.
Response on Success:
See Format for Networks. Note that networkJSON is not included in the response.
PUT /networks/:id
Edit a previously created network.
URL Parameters:
| Name | Type | Description |
|---|---|---|
| id* | String | The network id. Required. |
| *=required. |
Body Parameters:
See Format for Networks. Body parameters must include required keys and should not include internal keys.
Response on Success:
See Format for Networks. Note that networkJSON is not included in the response.
DELETE /networks/:id
Delete a network.
URL Parameters:
| Name | Type | Description |
|---|---|---|
| id* | String | The network id. Required. |
| *=required. |
Response on Success:
200
Format for Networks
| Name | Level | Type | Description |
|---|---|---|---|
| _idⁱ | 1 | String | The network id. |
| billingⁱ | 1 | Object | Object encapsulating billing settings for the network. |
| maxViews | 2 | Number | The maximum number of views that can be saved for the network. |
| createdⁱ | 1 | Date | The date that the network was created. |
| description | 1 | String | The network description. |
| fileTypeⁱ | 1 | String | JSON or GEXF. |
| handpickedⁱ | 1 | Boolean | Whether this network is handpicked or not, i.e. is it highlighted as a handpicked network under discover. |
| isDirected | 1 | Boolean | Whether this network is directed or undirected. |
| modifiedⁱ | 1 | Date | The date that the network was last modified. |
| name* | 1 | String | Name of the network. |
| networkJSON* | 1 | Object | A JSON object containing the network data. See Format for Network JSON. |
| originalFileTypeⁱ | 1 | String | Excel, JSON or GEXF. |
| networkUUIDⁱ | 1 | String | A unique identifier for the network that changes when the network JSON is updated. |
| status | 1 | String | Public or Private. Public networks are publicly available. Access to private networks is restricted. Defaults to Private if omitted. |
| *=required. |
ⁱ=internal.
Format for Network JSON
The format of the actual network data is JSON and is detailed below.
Network JSON:
| Name | Level | Type | Description |
|---|---|---|---|
| nodes* | 1 | Object[] | An array of node objects for the network with properties as detailed below. Required. |
| id* | 2 | String or Number | The id of the node. Required for each node. |
| attributes | 2 | Object[] | An array of attribute objects for the node. Optional. |
| [attribute name] | 3 | String or Number | For each attribute included for the node a key / value pair where the key is the name of the attribute and the value is the value of the attribute. Github flavored markdown is supported for both [attribute name] and value. There are a few special cases to be aware of: (1) If [attribute name] is ‘name’ then that value will be used for the label of the node. If no name is specified then the id of the node will be used. (2) If the first character in [attribute name] is “_” then that attribute will be included and available to size by, color by, filter by, etc. but the attribute will be hidden in the right hand side window. Please ensure that numerical attributes are of type Number rather than String. If they are Strings they will be treated as categorical attributes. An attribute whose value is an empty string or null is treated as "no value" and is not stored, so an attribute is either present with a value or absent. |
| x | 2 | Number | The x coordinate of the node. Optional. If none is specified then nodes will be equally distributed on a circle to begin with. |
| y | 2 | Number | The y coordinate of the node. Optional. If none is specified then nodes will be equally distributed on a circle to begin with. |
| image | 2 | Object | Object encapsulating image settings for a node below. Optional. |
| url | 3 | String | A url for an image to render inside the node. Defaults to no image. Many popular services for images such as LinkedIn and Twitter will automatically add an Access-Control-Allow-Origin header to their response. However, if you use images from a URL that does not add this header you will need to prepend a third-party proxy such as https://crossorigin.me to the URL. For example, you may enter something like: https://crossorigin.me/http://url.com/imageName.jpg. Alternatively, you can upload images to a CDN such as Cloudfront and use the URLs from that CDN, being sure to enable CORS for polinode.com at a minimum. |
| edges | 1 | Object[] | An array of edge objects for the network with properties as detailed below. |
| id* | 2 | String or Number | The id of the edge. Required for each edge. |
| source* | 2 | String or Number | The id of the node where the edge starts from. If the network is undirected then source and target are interchangeable. Required for each edge. |
| target* | 2 | String or Number | The id of the node where the edge ends. If the network is undirected then source and target are interchangeable. Required for each edge. |
| attributes | 2 | Object[] | An array of attribute objects for the edge. Optional. |
| [attribute name] | 3 | String or Number | For each attribute included for the edge a key / value pair where the key is the name of the attribute and the value is the value of the attribute. Github flavored markdown is supported for both [attribute name] and value. There is one special case to be aware of: If the first character in [attribute name] is “_” then that attribute will be included and available to size by, color by, filter by, etc. but the attribute will be hidden in the right hand side window Please ensure that numerical attributes are of type Number rather than String. If they are Strings they will be treated as categorical attributes. An attribute whose value is an empty string or null is treated as "no value" and is not stored, so an attribute is either present with a value or absent. |
| *=required. |
Network JSON Example:
{
'nodes':[
{
'id': 'Joe',
'attributes':
{
'Example Numerical Attribute Name': 24,
'Example Categorical Attribute Name': "Value 1",
'Name': 'Joe'
}
},
{
'id':'Mary',
'attributes':
{
'Example Numerical Attribute Name':38,
'Example Categorical Attribute Name':"Value 1",
'Name':'Mary'
}
},
{
'id':'Bill',
'attributes':
{
'Example Numerical Attribute Name':65,
'Example Categorical Attribute Name':"Value 2",
'Name':'Bill'
}
},
{
'id':'Grant',
'attributes':
{
'Example Numerical Attribute Name':52,
'Example Categorical Attribute Name':"Value 2",
'Name':'Grant'
}
}
],
'edges':[
{
'id':0,
'source':'Joe',
'target':'Mary',
'attributes':
{
'Example Numerical Attribute Name':30,
'Example Categorical Attribute Name':"Value 1"
}
},
{
'id':1,
'source':'Grant',
'target':'Mary',
'attributes':
{
'Example Numerical Attribute Name':34,
'Example Categorical Attribute Name':"Value 1"
}
},
{
'id':2,
'source':'Bill',
'target':'Joe',
'attributes':
{
'Example Numerical Attribute Name':38,
'Example Categorical Attribute Name':"Value 2"
}
}
]
};
Metrics API
ENTERPRISE USERS
The Metrics API is only available to Enterprise and Partner accounts.
Compute time for all metrics is limited to 60 seconds for each call.
Network Metrics
POST /metrics/network/modularity
Modularity is a measure of the degree to which a network is divided or separated into non-overlapping groups or communities. Whereas the Communities metric finds communities that optimises modularity, the modularity metric takes communities as an input and outputs modularity. It is a value between -1 and 1. Directed networks will be converted into undirected networks. Read more here.
Body Parameters:
| Name | Level | Type | Description |
|---|---|---|---|
| attribute** | 1 | String | The node attribute that contains the communities to measure modularity with respect to. |
| metricEdgeWeights | 1 | String or Boolean | If True then the weight value on edges will be used, if a string is provided then that edge attribute will be used as the edge weight. |
| networkId* | 1 | String | The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated. |
| networkJSON* | 1 | Object | A JSON object containing the network data. See Format for Network JSON. |
*One and only one of these two parameters must be provided.
**=required
Response on Success:
A single number is returned regardless of whether networkId or networkJSON is provided.
POST /metrics/network/diameter
Diameter measures the length of the longest shortest path across the network. Only the largest connected component is considered (if applicable). Directed networks are converted to undirected networks when calculating diameter. Read more here.
Body Parameters:
| Name | Level | Type | Description |
|---|---|---|---|
| networkId* | 1 | String | The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated. |
| networkJSON* | 1 | Object | A JSON object containing the network data. See Format for Network JSON. |
*One and only one of these two parameters must be provided.
Response on Success:
A single number is returned regardless of whether networkId or networkJSON is provided.
POST /metrics/network/avgShortestPathLength
The average shortest path length of a network is the average of all shortest paths between all pairs of nodes in the network. Where two nodes cannot reach each other that path is excluded. Read more here.
Body Parameters:
| Name | Level | Type | Description |
|---|---|---|---|
| networkId* | 1 | String | The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated. |
| networkJSON* | 1 | Object | A JSON object containing the network data. See Format for Network JSON. |
*One and only one of these two parameters must be provided.
Response on Success:
A single number is returned regardless of whether networkId or networkJSON is provided.
Node Metrics
POST /metrics/nodes/averageNeighborDegree
Average Neighbor Degree for a node is the average number of edges (i.e. degree) that a node's neighbors have. For directed networks, you can specify whether to use in-degree or out-degree for each of the source and target nodes in the calculation. Read more here.
Body Parameters:
| Name | Level | Type | Description |
|---|---|---|---|
| averageNeighborDegreeSource | 1 | String | For directed networks, either 'in' or 'out'. Defaults to 'out'. |
| averageNeighborDegreeTarget | 1 | String | For directed networks, either 'in' or 'out'. Defaults to 'out'. |
| directed | 1 | Boolean | If True then the network is a directed network. If False then the network is an undirected network. Defaults to True. |
| metricEdgeWeights | 1 | String or Boolean | If True then the weight value on edges will be used, if a string is provided then that edge attribute will be used as the edge weight. |
| networkId* | 1 | String | The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated. |
| networkJSON* | 1 | Object | A JSON object containing the network data. See Format for Network JSON. |
*One and only one of these two parameters must be provided.
Response on Success:
If networkJSON is provided directly then the metric is returned as a response. If a networkID is provided then the result is saved directly on the associated networkJSON and a response of 200 is returned.
POST /metrics/nodes/antiCommunities
Anti-Communities are the mirror image of communities: groups chosen so that connections WITHIN a group are as rare as possible and connections BETWEEN groups as common as possible. They are useful for finding sets of people who are each well connected across the organisation but barely connected to one another. The attribute "Anti-Community" is added to each node. The network is treated as undirected, self-loops are ignored and edge weights are not used.
Body Parameters:
| Name | Level | Type | Description |
|---|---|---|---|
| antiCommunityGroupCount | 1 | Number | The number of groups to partition the network into, at least 2. Clamped to the number of nodes. Defaults to 10. |
| networkId* | 1 | String | The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated. |
| networkJSON* | 1 | Object | A JSON object containing the network data. See Format for Network JSON. |
*One and only one of these two parameters must be provided.
Response on Success:
If networkJSON is provided directly then the metric is returned as a response. If a networkID is provided then the result is saved directly on the associated networkJSON and a response of 200 is returned.
POST /metrics/nodes/betweennessCentrality
Betweenness Centrality for a node is the total number of shortest paths that pass through that node divided by the total number of shortest paths in the network. It is a measure of how much a node is a 'bridge' between other nodes in the network. Read more here.
Body Parameters:
| Name | Level | Type | Description |
|---|---|---|---|
| directed | 1 | Boolean | If True then the network is a directed network. If False then the network is an undirected network. Defaults to True. |
| kPercent | 1 | Number | The percentage of nodes to sample (between 0 and 100). Other than for very large networks where betweenness cannot be calculated within 60 seconds, kPercent should be left at 100. Defaults to 100. |
| metricEdgeWeights | 1 | String or Boolean | If True then the weight value on edges will be used, if a string is provided then that edge attribute will be used as the edge weight. |
| networkId* | 1 | String | The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated. |
| networkJSON* | 1 | Object | A JSON object containing the network data. See Format for Network JSON. |
| normalized | 1 | Boolean | If True then the metric will be normalized. Defaults to True. |
*One and only one of these two parameters must be provided.
Response on Success:
If networkJSON is provided directly then the metric is returned as a response. If a networkID is provided then the result is saved directly on the associated networkJSON and a response of 200 is returned.
POST /metrics/nodes/brokerage
Brokerage here refers to Gould-Fernandez brokerage. Given an attribute, there are five kinds of brokerage possible: Coordinator, Consultant, Gatekeeper, Representative and Liaison. This metric will count up and return the number of times that a node acted in each of those roles. Read more here.
Body Parameters:
| Name | Level | Type | Description |
|---|---|---|---|
| partition | 1 | Object | A mapping of nodes by node id to a group that will be used to calculate brokerage. Every node must be mapped to a group, i.e. each node id must be included. |
| metricEdgeWeights | 1 | String or Boolean | If True then the weight value on edges will be used, if a string is provided then that edge attribute will be used as the edge weight. |
| networkId* | 1 | String | The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated. |
| networkJSON* | 1 | Object | A JSON object containing the network data. See Format for Network JSON. |
*One and only one of these two parameters must be provided.
Response on Success:
If networkJSON is provided directly then the metric is returned as a response. If a networkID is provided then the result is saved directly on the associated networkJSON and a response of 200 is returned.
POST /metrics/nodes/closenessCentrality
Closeness Centrality for a node is the reciprocal of its farness. The farness of a node is the sum of its shortest path distances from all other nodes. The greater a node's Closeness Centrality relative to other nodes, the closer it is on average to other nodes in the network. Read more here.
Body Parameters:
| Name | Level | Type | Description |
|---|---|---|---|
| directed | 1 | Boolean | If True then the network is a directed network. If False then the network is an undirected network. Defaults to True. |
| kPercent | 1 | Number | The percentage of nodes to sample (between 0 and 100). Other than for very large networks where closeness cannot be calculated within 60 seconds, kPercent should be left at 100. If kPercent is less than 100 then closeness will only be calculated for the giant component (i.e. largest connected component in the network). Defaults to 100. |
| metricEdgeWeights | 1 | String or Boolean | If True then the weight value on edges will be used, if a string is provided then that edge attribute will be used as the edge weight. |
| networkId* | 1 | String | The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated. |
| networkJSON* | 1 | Object | A JSON object containing the network data. See Format for Network JSON. |
| normalized | 1 | Boolean | If True then the metric will be normalized. Defaults to True. |
*One and only one of these two parameters must be provided.
Response on Success:
If networkJSON is provided directly then the metric is returned as a response. If a networkID is provided then the result is saved directly on the associated networkJSON and a response of 200 is returned.
POST /metrics/nodes/constraint
Constraint is related to the concept of structural holes and measures the extent to which a node is able to take advantage of structural holes in their network. Constraint will be higher if a node's connections are highly connected between each other, either directly or indirectly through a mutual connection. Read more here.
Body Parameters:
| Name | Level | Type | Description |
|---|---|---|---|
| metricEdgeWeights | 1 | String or Boolean | If True then the weight value on edges will be used, if a string is provided then that edge attribute will be used as the edge weight. |
| networkId* | 1 | String | The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated. |
| networkJSON* | 1 | Object | A JSON object containing the network data. See Format for Network JSON. |
*One and only one of these two parameters must be provided.
Response on Success:
If networkJSON is provided directly then the metric is returned as a response. If a networkID is provided then the result is saved directly on the associated networkJSON and a response of 200 is returned.
POST /metrics/nodes/clustering
The Clustering coefficient for a node is the fraction of possible triangles through that node that actually exist. The higher a node's clustering coefficient, the more embedded it is in the overall network. Read more here.
Body Parameters:
| Name | Level | Type | Description |
|---|---|---|---|
| directed | 1 | Boolean | If True then the network is a directed network. If False then the network is an undirected network. Defaults to True. |
| metricEdgeWeights | 1 | String or Boolean | If True then the weight value on edges will be used, if a string is provided then that edge attribute will be used as the edge weight. |
| networkId* | 1 | String | The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated. |
| networkJSON* | 1 | Object | A JSON object containing the network data. See Format for Network JSON. |
*One and only one of these two parameters must be provided.
Response on Success:
If networkJSON is provided directly then the metric is returned as a response. If a networkID is provided then the result is saved directly on the associated networkJSON and a response of 200 is returned.
POST /metrics/nodes/communities
Louvain Communities are non-overlapping groups of relatively closely connected nodes found by an optimization algorithm. Directed networks will be converted into undirected networks for the purposes of calculating this metric. Read more here.
Body Parameters:
| Name | Level | Type | Description |
|---|---|---|---|
| allLevels | 1 | Boolean | The algorithm successively finds groups / communities and aggregates them. If allLevels is set to True then all the levels in this process will be outputted. If False then just the final level (with the least number of communities) will be outputted. Defaults to False. The algorithm is considerably faster if allLevels is either not set or set to False. |
| metricEdgeWeights | 1 | String or Boolean | If True then the weight value on edges will be used, if a string is provided then that edge attribute will be used as the edge weight. |
| networkId* | 1 | String | The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated. |
| networkJSON* | 1 | Object | A JSON object containing the network data. See Format for Network JSON. |
| resolution | 1 | Number | A parameter that can be used to control how many communities are outputted. Modularity is optimized (heuristically) with resolution set to to 1. A resolution of 0 will place all nodes into a single community whereas of a resolution of two times the number of nodes will result in each node being assigned it's own community. Defaults to 1. |
| maxSize | 1 | Number | An optional maximum size for the resulting communities. By default there is no maximum size. Including a maximum size will mean that the algorithm will run considerably slower. |
*One and only one of these two parameters must be provided.
POST /metrics/nodes/complexCentrality
Complex Centrality measures how well placed a node is to spread a complex contagion - a behaviour or norm that people only adopt once several of the people around them have already adopted it, as opposed to a piece of news that passes on from a single contact. Two attributes are added to each node: "Complex Centrality", the average distance the contagion travelled from that node, and "Complex Centrality - Reach", the number of nodes that ended up adopting. The network is treated as undirected and edge weights are ignored. Read more here.
Body Parameters:
| Name | Level | Type | Description |
|---|---|---|---|
| complexCentralityThreshold | 1 | Number | The tipping point at which a node adopts. With an absolute threshold this is a whole number of adopting neighbours (defaults to 3); with a fractional threshold it is a proportion of the node's neighbours, greater than 0 and at most 1. |
| complexCentralityThresholdType | 1 | String | Either 'absolute' or 'fractional'. Defaults to 'absolute'. |
| normalized | 1 | Boolean | If True then Complex Centrality is rescaled to a 0 to 1 range across the network. Defaults to False. |
| networkId* | 1 | String | The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated. |
| networkJSON* | 1 | Object | A JSON object containing the network data. See Format for Network JSON. |
*One and only one of these two parameters must be provided.
Response on Success:
If networkJSON is provided directly then the metric is returned as a response. If a networkID is provided then the result is saved directly on the associated networkJSON and a response of 200 is returned.
POST /metrics/nodes/connectedComponents
A Connected Component is a set of nodes that are connected to each other. A directed network will be treated as an undirected network for the calculation of Connected Components. Read more here.
Body Parameters:
| Name | Level | Type | Description |
|---|---|---|---|
| networkId* | 1 | String | The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated. |
| networkJSON* | 1 | Object | A JSON object containing the network data. See Format for Network JSON. |
*One and only one of these two parameters must be provided.
Response on Success:
If networkJSON is provided directly then the metric is returned as a response. If a networkID is provided then the result is saved directly on the associated networkJSON and a response of 200 is returned.
POST /metrics/nodes/coreNumber
Returns the core number for each node. The core number for a node is the largest value k of all k-cores containing that node where a k-core is the largest possible subgraph in the network containing nodes with a Total Degree of k or more. Core Numbers can be helpful in the decomposition of large networks. Read more here.
Body Parameters:
| Name | Level | Type | Description |
|---|---|---|---|
| networkId* | 1 | String | The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated. |
| networkJSON* | 1 | Object | A JSON object containing the network data. See Format for Network JSON. |
*One and only one of these two parameters must be provided.
Response on Success:
If networkJSON is provided directly then the metric is returned as a response. If a networkID is provided then the result is saved directly on the associated networkJSON and a response of 200 is returned.
POST /metrics/nodes/corePeriphery
Core Periphery will partition the network into a group of nodes that are said to be in the "Core" and a set of nodes said to be in the "Periphery". There are two options for type - Single and Multiple. If Single is chosen then the network will be partioned into a single core / periphery using the approach of Rombach et al. (2017). This algorithm takes two inputs - alpha and beta. Alpha is a value between 0 and 1 that determines the fuziness of the core / periphery boundary. If alpha is set to 0 the boundary is the fuzziest and if it's set to 1 the boundary is the sharpest. Beta, also between 0 and 1, is the fraction of nodes to be used for the periphery. If Multiple is selected for type then the algorithm detailed in Kojaku and Masuda (2018) is used. There are no input parameters for this algorithm but please note that the configuration model is used. The output of the algorithm is two attributes that are added to all nodes - Core Periphery and Coreness. For the Single algorithm Core Periphery is always "Core 1" and Coreness is a value between 0 and 1 with values closer to 0 indicating a more peripheral node. For the Multiple algorithm there may be multiple cores, named "Core 1", "Core 2" and so on by the Core Periphery attribute, and Coreness is a discrete value that is either 0 (periphery) or 1 (core) for the core that the node is a member of. Note that the Multiple algorithm can find a large number of small cores in a network that has no real core-periphery structure, so it is worth checking how many it produced before reading anything into them. The network is treated as undirected and edge weights are ignored. Read more here.
Body Parameters:
| Name | Level | Type | Description |
|---|---|---|---|
| networkId* | 1 | String | The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated. |
| networkJSON* | 1 | Object | A JSON object containing the network data. See Format for Network JSON. |
| type | 1 | String | Either single or multiple. Defaults to single. Determines the type of algorithm that will be used for core / periphery detection, one that assumes a single core or one that allows for multiple potential cores. |
| alpha | 1 | Number | If type is set to single then this alpha parameter will determine the sharpness of the separation between core and periphery. Defaults to 0.5. |
| beta | 1 | Number | If type is set to single then this beta parameter will determine the proportion of peripheral nodes. Defaults to 0.8. |
*One and only one of these two parameters must be provided.
Response on Success:
If networkJSON is provided directly then the metric is returned as a response. If a networkID is provided then the result is saved directly on the associated networkJSON and a response of 200 is returned.
POST /metrics/nodes/currentFlowClosenessCentrality
Current Flow Closeness Centrality is similar to regular Closeness Centrality but instead of a shortest path measure for distance, effective resistance inspired by electric circuit models is used. Directed networks will be converted to undirected networks. Read more here.
Body Parameters:
| Name | Level | Type | Description |
|---|---|---|---|
| metricEdgeWeights | 1 | String or Boolean | If True then the weight value on edges will be used, if a string is provided then that edge attribute will be used as the edge weight. |
| networkId* | 1 | String | The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated. |
| networkJSON* | 1 | Object | A JSON object containing the network data. See Format for Network JSON. |
*One and only one of these two parameters must be provided.
Response on Success:
If networkJSON is provided directly then the metric is returned as a response. If a networkID is provided then the result is saved directly on the associated networkJSON and a response of 200 is returned.
POST /metrics/nodes/effectiveSize
Effective Size is related to the concept of structural holes and the redundancy of connections. It measures the number of people that the node is connected to but controlling for (i.e. reducing by) the redundancy of those connections. Read more here.
Body Parameters:
| Name | Level | Type | Description |
|---|---|---|---|
| metricEdgeWeights | 1 | String or Boolean | If True then the weight value on edges will be used, if a string is provided then that edge attribute will be used as the edge weight. |
| networkId* | 1 | String | The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated. |
| networkJSON* | 1 | Object | A JSON object containing the network data. See Format for Network JSON. |
*One and only one of these two parameters must be provided.
Response on Success:
If networkJSON is provided directly then the metric is returned as a response. If a networkID is provided then the result is saved directly on the associated networkJSON and a response of 200 is returned.
POST /metrics/nodes/efficiency
Efficiency is equal to effective size divided by total degree. If a node has no redundant ties then the effective size will be equal to total degree and efficiency will be equal to one. Efficiency is the proportion of a node's ties that are non-redundant. Read more here.
Body Parameters:
| Name | Level | Type | Description |
|---|---|---|---|
| metricEdgeWeights | 1 | String or Boolean | If True then the weight value on edges will be used, if a string is provided then that edge attribute will be used as the edge weight. |
| networkId* | 1 | String | The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated. |
| networkJSON* | 1 | Object | A JSON object containing the network data. See Format for Network JSON. |
*One and only one of these two parameters must be provided.
Response on Success:
If networkJSON is provided directly then the metric is returned as a response. If a networkID is provided then the result is saved directly on the associated networkJSON and a response of 200 is returned.
POST /metrics/nodes/eigenvectorCentrality
Eigenvector Centrality is motivated by the idea that nodes connected to other nodes that are central should themselves be relatively central, i.e. being connected to a central node contributes more than being connected to a non-central node. It is not always well defined for directed networks and it's generally preferable to calculate Katz Centrality for directed networks. However, should you calculate eigenvector centrality for a directed network Polinode will return "left" eigenvector centrality (i.e. corresponding to the in-edges). Read more here.
Body Parameters:
| Name | Level | Type | Description |
|---|---|---|---|
| metricEdgeWeights | 1 | String or Boolean | If True then the weight value on edges will be used, if a string is provided then that edge attribute will be used as the edge weight. |
| networkId* | 1 | String | The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated. |
| networkJSON* | 1 | Object | A JSON object containing the network data. See Format for Network JSON. |
*One and only one of these two parameters must be provided.
Response on Success:
If networkJSON is provided directly then the metric is returned as a response. If a networkID is provided then the result is saved directly on the associated networkJSON and a response of 200 is returned.
POST /metrics/nodes/externalVsInternal
External vs Internal (EI) calculates, for a given attribute, the percentage of a node's edges that connect to nodes that do not share the same value for that attribute (external connections) vs connections to nodes that do share the same attribute value (internal connections). If type is Total the metric will be calculated for all edges, if type is In then the metric will be calculated only for a node's incoming edges and if type is Out then only for a node's outgoing edges.
Body Parameters:
| Name | Level | Type | Description |
|---|---|---|---|
| attribute | 1 | String | The attribute that external vs internal is calculated with respect to. |
| networkId* | 1 | String | The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated. |
| networkJSON* | 1 | Object | A JSON object containing the network data. See Format for Network JSON. |
| type | 1 | String | How to calculate the metric - 'total', 'in' or 'out'. Defaults to 'total.' |
*One and only one of these two parameters must be provided.
Response on Success:
If networkJSON is provided directly then the metric is returned as a response. If a networkID is provided then the result is saved directly on the associated networkJSON and a response of 200 is returned.
POST /metrics/nodes/harmonicCentrality
Harmonic Centrality for a node is the sum of the reciprocals of the shortest path distances from that node to each other node in the network. It is closely related to Closeness Centrality with the key difference being that the reciprocal is taken for each distance rather than taking the reciprocal of the sums of the distances. Read more here.
Body Parameters:
| Name | Level | Type | Description |
|---|---|---|---|
| networkId* | 1 | String | The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated. |
| networkJSON* | 1 | Object | A JSON object containing the network data. See Format for Network JSON. |
*One and only one of these two parameters must be provided.
Response on Success:
If networkJSON is provided directly then the metric is returned as a response. If a networkID is provided then the result is saved directly on the associated networkJSON and a response of 200 is returned.
POST /metrics/nodes/HITS
Hyperlink-Induced Topic Search (HITS) for a node gives two metrics - Hubs and Authorities. A node has a relatively high Hubs score if it links to other nodes and a relatively high Authority score if it is linked to by other nodes. Read more here.
Body Parameters:
| Name | Level | Type | Description |
|---|---|---|---|
| networkId* | 1 | String | The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated. |
| networkJSON* | 1 | Object | A JSON object containing the network data. See Format for Network JSON. |
| normalized | 1 | Boolean | If True then the metric will be normalized. Defaults to True. |
*One and only one of these two parameters must be provided.
Response on Success:
If networkJSON is provided directly then the metric is returned as a response. If a networkID is provided then the result is saved directly on the associated networkJSON and a response of 200 is returned.
POST /metrics/nodes/identifyInfluencers
Identify Influencers is a heuristic that finds the most influential nodes in the network in the sense that together the count of those nodes and the nodes connected to those nodes (in either direction for directed networks) is maximised, i.e. coverage of the network is maximised.
Body Parameters:
| Name | Level | Type | Description |
|---|---|---|---|
| direction | 1 | String | One of 'total', 'in' or 'out'. Defaults to 'total'. |
| identifyInfluencersAttribute | 1 | String | An optional name of an attribute that the algorithm will limit the identification of influencers with respect to. |
| identifyInfluencersAttributeValues | 1 | Array | An optional array of attribute values for the identifyInfluencersAttribute that the algorithm will limit the identification of influencers to, i.e. influencers must have one of these values for the identified attribute |
| identifyInfluencersMethod | 1 | String | The method to use, either 'coverage' or 'count'. Defaults to 'coverage'. |
| influencersCount | 1 | Number | If the method is 'count', the total number of influencers to target. |
| networkId* | 1 | String | The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated. |
| networkJSON* | 1 | Object | A JSON object containing the network data. See Format for Network JSON. |
| targetCoveragePercent | 1 | Number | If the method is 'coverage', the percentage coverage to target (between 0 and 100). Defaults to 90. |
*One and only one of these two parameters must be provided.
Response on Success:
If networkJSON is provided directly then the metric is returned as a response. If a networkID is provided then the result is saved directly on the associated networkJSON and a response of 200 is returned.
POST /metrics/nodes/inDegree
In Degree for a node is a straightforward measure of centrality - it measures the total number of nodes linking to that node. Read more here.
Body Parameters:
| Name | Level | Type | Description |
|---|---|---|---|
| metricEdgeWeights | 1 | String or Boolean | If True then the weight value on edges will be used, if a string is provided then that edge attribute will be used as the edge weight. |
| networkId* | 1 | String | The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated. |
| networkJSON* | 1 | Object | A JSON object containing the network data. See Format for Network JSON. |
| type | 1 | String | Either 'sum' or 'average'. If metricEdgeWeights is True or a string then type determines how those edge weights will be used, either summed or averaged. |
*One and only one of these two parameters must be provided.
Response on Success:
If networkJSON is provided directly then the metric is returned as a response. If a networkID is provided then the result is saved directly on the associated networkJSON and a response of 200 is returned.
POST /metrics/nodes/informalAlignment
Informal Alignment compares the people a node actually works with against the part of the organisation chart they sit in, and scores how far the two agree. Both structures are read from the one network: an edge attribute and the values of it that mark a formal connection, and an edge attribute and the values of it that mark an informal one. The attribute "Informal Alignment" is added to each node, ranging from 0 (the node's informal connections fall entirely outside its formal neighbourhood) to 1 (they fall entirely within it). Nodes with no informal connections are not scored. Both structures are treated as undirected and edge weights are ignored. This endpoint is available to organization accounts only.
Body Parameters:
| Name | Level | Type | Description |
|---|---|---|---|
| fiFormalAttribute | 1 | String | The name of an EDGE attribute whose values mark the formal structure, e.g. a 'Type' attribute where a value of 'Reports To' marks a reporting line. |
| fiFormalValues | 1 | Array | The values of fiFormalAttribute that mark a formal connection. At least one is required. |
| fiInformalAttribute | 1 | String | The name of an EDGE attribute whose values mark the informal structure. May be the same attribute as fiFormalAttribute. |
| fiInformalValues | 1 | Array | The values of fiInformalAttribute that mark an informal connection. At least one is required. |
| networkId* | 1 | String | The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated. |
| networkJSON* | 1 | Object | A JSON object containing the network data. See Format for Network JSON. |
*One and only one of these two parameters must be provided.
Response on Success:
If networkJSON is provided directly then the metric is returned as a response. If a networkID is provided then the result is saved directly on the associated networkJSON and a response of 200 is returned.
POST /metrics/nodes/informalDistance
Informal Distance measures how far across the organisation chart a node's actual working relationships reach. For every informal connection it takes the distance between its two ends through the formal structure, and a node's score is the average over its own informal connections. Both structures are read from the one network, exactly as for Informal Alignment. Two attributes are added to each node: "Informal Distance" and "Informal Distance - Ranked", the latter being a 0 to 1 rank in which the shortest distances rank highest. Connections with no formal path between their ends are ignored, and a node with no scored connection is not scored. Both structures are treated as undirected and edge weights are ignored. This endpoint is available to organization accounts only.
Body Parameters:
| Name | Level | Type | Description |
|---|---|---|---|
| fiFormalAttribute | 1 | String | The name of an EDGE attribute whose values mark the formal structure, e.g. a 'Type' attribute where a value of 'Reports To' marks a reporting line. |
| fiFormalValues | 1 | Array | The values of fiFormalAttribute that mark a formal connection. At least one is required. |
| fiInformalAttribute | 1 | String | The name of an EDGE attribute whose values mark the informal structure. May be the same attribute as fiFormalAttribute. |
| fiInformalValues | 1 | Array | The values of fiInformalAttribute that mark an informal connection. At least one is required. |
| networkId* | 1 | String | The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated. |
| networkJSON* | 1 | Object | A JSON object containing the network data. See Format for Network JSON. |
*One and only one of these two parameters must be provided.
Response on Success:
If networkJSON is provided directly then the metric is returned as a response. If a networkID is provided then the result is saved directly on the associated networkJSON and a response of 200 is returned.
POST /metrics/nodes/kCliqueCommunities
A K Clique Community is the union of all cliques of size k that can be reached through adjacent k-cliques where a k-clique is a group of k nodes that are all connected to each other and a k-clique is said to be adjacent to another k-clique if it shares k-1 nodes with it. Communities produced by this algorithm are generally not distinct and will overlap so an attribute is added for each community found. Directed networks will be converted to undirected networks for the puroses of calculating this metric. Read more here.
Body Parameters:
| Name | Level | Type | Description |
|---|---|---|---|
| kCliqueCommunities | 1 | Number | The clique size, k. Defaults to 2. |
| networkId* | 1 | String | The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated. |
| networkJSON* | 1 | Object | A JSON object containing the network data. See Format for Network JSON. |
*One and only one of these two parameters must be provided.
Response on Success:
If networkJSON is provided directly then the metric is returned as a response. If a networkID is provided then the result is saved directly on the associated networkJSON and a response of 200 is returned.
POST /metrics/nodes/katzCentrality
Katz Centrality for a node takes into account not just the neighbors of that node but also their neighbors and so on, applying an attenuation factor of alpha so that the influence of nodes declines on every step away from the target node. Read more here.
Body Parameters:
| Name | Level | Type | Description |
|---|---|---|---|
| katzCentralityAlpha | 1 | Number | Attenuation factor. Defaults to 0.1. |
| metricEdgeWeights | 1 | String or Boolean | If True then the weight value on edges will be used, if a string is provided then that edge attribute will be used as the edge weight. |
| networkId* | 1 | String | The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated. |
| networkJSON* | 1 | Object | A JSON object containing the network data. See Format for Network JSON. |
| normalized | 1 | Boolean | If True then the metric will be normalized. Defaults to True. |
*One and only one of these two parameters must be provided.
Response on Success:
If networkJSON is provided directly then the metric is returned as a response. If a networkID is provided then the result is saved directly on the associated networkJSON and a response of 200 is returned.
POST /metrics/nodes/loadCentrality
Load Centrality for a node is the total amount of some commodity passing through that node when one unit of the commodity is sent from each node in the network to each other node in the network and the commodity is split equally at branching points and aggregated at meeting points.. Load Centrality is very similar to Betweenness Centrality and also measures 'bridging'. Read more here.
Body Parameters:
| Name | Level | Type | Description |
|---|---|---|---|
| metricEdgeWeights | 1 | String or Boolean | If True then the weight value on edges will be used, if a string is provided then that edge attribute will be used as the edge weight. |
| networkId* | 1 | String | The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated. |
| networkJSON* | 1 | Object | A JSON object containing the network data. See Format for Network JSON. |
| normalized | 1 | Boolean | If True then the metric will be normalized. Defaults to True. |
*One and only one of these two parameters must be provided.
Response on Success:
If networkJSON is provided directly then the metric is returned as a response. If a networkID is provided then the result is saved directly on the associated networkJSON and a response of 200 is returned.
POST /metrics/nodes/outDegree
Out Degree for a node is a straightforward measure of centrality - it measures the total number of nodes that that node links to. Read more here.
Body Parameters:
| Name | Level | Type | Description |
|---|---|---|---|
| metricEdgeWeights | 1 | String or Boolean | If True then the weight value on edges will be used, if a string is provided then that edge attribute will be used as the edge weight. |
| networkId* | 1 | String | The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated. |
| networkJSON* | 1 | Object | A JSON object containing the network data. See Format for Network JSON. |
| type | 1 | String | Either 'sum' or 'average'. If metricEdgeWeights is True or a string then type determines how those edge weights will be used, either summed or averaged. |
*One and only one of these two parameters must be provided.
Response on Success:
If networkJSON is provided directly then the metric is returned as a response. If a networkID is provided then the result is saved directly on the associated networkJSON and a response of 200 is returned.
POST /metrics/nodes/pagerank
Pagerank for a node is a ranking of relative importance in the network based on the structure of incoming edges for that node. It was originally designed to rank web pages. Similar to Katz Centrality, alpha is an attenuation factor. Pagerank for undirected networks will be calculated by transforming each undirected edge into two directed edges. Read more here.
Body Parameters:
| Name | Level | Type | Description |
|---|---|---|---|
| pagerankAlpha | 1 | Number | Attenuation factor. Defaults to 0.85. |
| metricEdgeWeights | 1 | String or Boolean | If True then the weight value on edges will be used, if a string is provided then that edge attribute will be used as the edge weight. |
| networkId* | 1 | String | The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated. |
| networkJSON* | 1 | Object | A JSON object containing the network data. See Format for Network JSON. |
*One and only one of these two parameters must be provided.
Response on Success:
If networkJSON is provided directly then the metric is returned as a response. If a networkID is provided then the result is saved directly on the associated networkJSON and a response of 200 is returned.
POST /metrics/nodes/totalDegree
Total Degree for a node is a straightforward measure of centrality. It is simply the total number of edges that that node has, i.e. for directed networks it is the sum of In Degree and Out Degree. Read more here.
Body Parameters:
| Name | Level | Type | Description |
|---|---|---|---|
| metricEdgeWeights | 1 | String or Boolean | If True then the weight value on edges will be used, if a string is provided then that edge attribute will be used as the edge weight. |
| networkId* | 1 | String | The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated. |
| networkJSON* | 1 | Object | A JSON object containing the network data. See Format for Network JSON. |
| type | 1 | String | Either 'sum' or 'average'. If metricEdgeWeights is True or a string then type determines how those edge weights will be used, either summed or averaged. |
*One and only one of these two parameters must be provided.
Response on Success:
If networkJSON is provided directly then the metric is returned as a response. If a networkID is provided then the result is saved directly on the associated networkJSON and a response of 200 is returned.
Edge Metrics
POST /metrics/edges/edgeBetweennessCentrality
Edge betweenness is a measure of the total number of shortest path in the network that pass through an edge relative to the total number of shortest paths in the network overall.
Body Parameters:
| Name | Level | Type | Description |
|---|---|---|---|
| metricEdgeWeights | 1 | String or Boolean | If True then the weight value on edges will be used, if a string is provided then that edge attribute will be used as the edge weight. |
| networkId* | 1 | String | The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated. |
| networkJSON* | 1 | Object | A JSON object containing the network data. See Format for Network JSON. |
| normalized | 1 | Boolean | If True then the metric will be normalized. Defaults to True. |
*One and only one of these two parameters must be provided.
Response on Success:
If networkJSON is provided directly then the metric is returned as a response. If a networkID is provided then the result is saved directly on the associated networkJSON and a response of 200 is returned.
Responses API
ENTERPRISE USERS
The Responses API is only available to Enterprise and Partner accounts.
GET /responses/:id
Retrieve a specific response.
URL Parameters:
| Name | Type | Description |
|---|---|---|
| id* | String | The response id. Required. This may be obtained in real-time via the Webhook on Completion or by downloading the full Respondent List. |
| *=required. |
Response on Success:
Please contact us for details on the format of responses.
For surveys with multiple languages enabled, the response carries a language field: the BCP 47 tag of the language the response was answered in (for example es or pt-BR), whether the respondent chose it from the language menu, it was passed in the link as ?lang=, or it was matched from the respondent's browser. It is an empty string for responses recorded before the survey used multiple languages. The same value is sent as language in the Webhook on Completion body, alongside responseUUID, and appears as the Response Language column in the respondent-list download and node attribute in generated networks.
Surveys API
ENTERPRISE USERS
The Surveys API is only available to Enterprise and Partner accounts.
POST /surveys/export/:id
Initiates an export of survey data, i.e. a combination of lists and responses. Please note that this starts a worker job that may take ~10 minutes to complete for larger surveys. This route should not be called more than once per day per survey.
URL Parameters:
| Name | Type | Description |
|---|---|---|
| id* | String | The survey id. Required. |
| *=required. |
Response on Success:
Will return the survey object on success (please contact support for details if needed). If the survey is already generating (i.e. export is in progress) then it will return an HTTP 200 OK success status response code.
GET /surveys/export/:id
Once the worker job is completed, this route will return a URL that can be used to retrieve the survey export (i.e. combined lists and responses). It will return {generatingSurveyJSON: true} if the survey is still generating. The returned URL is valid for 5 minutes.
URL Parameters:
| Name | Type | Description |
|---|---|---|
| id* | String | The survey id. Required. |
| *=required. |
Response on Success:
If the survey generation is complete it will return a URL to retrieve the export in the format {AWSURL: valueOfURL}. The returned URL is valid for 5 minutes. The route will return {generatingSurveyJSON: true} if the survey is still generating.
Employees API
ENTERPRISE USERS
The Employees API is only available to Enterprise and Partner accounts. Only organization Owners and Admins can access these endpoints.
The Employees API enables you to programmatically create, retrieve, update and delete employee records within your organization. Employee records use a rich nested schema with support for employment details, compensation, performance data, skills and more. You can also define custom fields on your organization and use them on employee records — see the Custom Fields API for details.
GET /employees
Retrieve all employees for the organization.
Query Parameters:
| Name | Type | Description |
|---|---|---|
| limit | Number | Maximum number of employees to return. Defaults to 100. Maximum is 1000. |
| offset | Number | Number of employees to skip for pagination. Defaults to 0. |
| department | String | Filter employees by department name. |
| employment.status | String | Filter by employment status. One of: active, inactive, terminated, on-leave, pending-start. |
Response on Success:
A paginated response containing an array of employees and pagination metadata:
{
"data": [ /* array of employee objects */ ],
"total": 150,
"limit": 100,
"offset": 0
}
Each employee in the array follows the Format for Employees.
GET /employees/:id
Retrieve a specific employee.
URL Parameters:
| Name | Type | Description |
|---|---|---|
| id* | String | The employee id. Required. |
| *=required. |
Response on Success:
See Format for Employees.
POST /employees
Create a new employee.
Body Parameters:
See Format for Employees. Body parameters must include required keys and should not include internal keys. If customFields are provided, each key is validated against the organization's Custom Field Definitions — unknown, archived, type-mismatched or missing required custom fields will return a 400 error.
Response on Success:
- See Format for Employees.
PUT /employees/:id
Replace an existing employee record. This is a full replacement — all fields not included in the request body will be removed.
URL Parameters:
| Name | Type | Description |
|---|---|---|
| id* | String | The employee id. Required. |
| *=required. |
Body Parameters:
See Format for Employees. Body parameters must include required keys and should not include internal keys. Custom fields are validated against the organization's definitions.
Response on Success:
See Format for Employees.
PATCH /employees/:id
Partially update an existing employee record. Only the fields provided in the request body will be updated. For customFields, the provided values are merged with existing values — existing custom field values not included in the request are preserved.
URL Parameters:
| Name | Type | Description |
|---|---|---|
| id* | String | The employee id. Required. |
| *=required. |
Body Parameters:
Any subset of fields from Format for Employees. Custom fields are validated against the organization's definitions after merging with existing values.
Response on Success:
See Format for Employees.
DELETE /employees/:id
Delete an employee.
URL Parameters:
| Name | Type | Description |
|---|---|---|
| id* | String | The employee id. Required. |
| *=required. |
Response on Success:
204
Format for Employees
| Name | Level | Type | Description |
|---|---|---|---|
| _idⁱ | 1 | String | Internal record identifier. Returned in responses and used as the id URL path parameter; never sent in request bodies. |
| employeeId | 1 | String | An external or legacy employee identifier. |
| email* | 1 | String | Work email address. Must be unique within the organization. Stored as lowercase. |
| personalEmail | 1 | String | Personal email address. |
| firstName | 1 | String | First name. |
| lastName | 1 | String | Last name. |
| middleName | 1 | String | Middle name. |
| preferredName | 1 | String | Preferred name. |
| displayName | 1 | String | Display name (used as the node label in generated networks). |
| username | 1 | String | Username. |
| dateOfBirth | 1 | Date | Date of birth in ISO 8601 format. |
| gender | 1 | String | One of: male, female, non-binary, prefer-not-to-say, other. |
| timezone | 1 | String | IANA timezone identifier (e.g. "America/New_York"). |
| pronouns | 1 | String | Pronouns. |
| ethnicity | 1 | String | Ethnicity. |
| race | 1 | String | Race. |
| nationality | 1 | String | Nationality. |
| citizenship | 1 | String | Citizenship. |
| disabilityStatus | 1 | String | One of: yes, no, prefer-not-to-say, undisclosed. |
| veteranStatus | 1 | String | One of: protected-veteran, not-a-veteran, prefer-not-to-say, undisclosed. |
| maritalStatus | 1 | String | One of: single, married, partnered, divorced, widowed, separated, prefer-not-to-say. |
| educationLevel | 1 | String | One of: none, primary, secondary, vocational, bachelors, masters, doctorate, other. |
| educationField | 1 | String | Field of study. |
| avatar | 1 | String | Avatar image URL. |
| address | 1 | Object | Employee's address. |
| street1 | 2 | String | Street address line 1. |
| street2 | 2 | String | Street address line 2. |
| city | 2 | String | City. |
| state | 2 | String | State or province. |
| postalCode | 2 | String | Postal or zip code. |
| country | 2 | String | Country. |
| employment | 1 | Object | Employment details. |
| status | 2 | String | Employment status. One of: active, inactive, terminated, on-leave, pending-start. |
| type | 2 | String | Employment type (working-time arrangement). One of: full-time, part-time, contractor, intern, temporary. |
| workerType | 2 | String | Worker type. One of: employee, contingent-worker. |
| workerSubtype | 2 | String | Worker subtype (e.g. "Regular", "Fixed Term", "Intern" — values vary by organization). |
| classification | 2 | String | One of: exempt, non-exempt, contractor. |
| fte | 2 | Number | Full-time equivalent (e.g. 1.0 for full-time, 0.5 for half-time). |
| contractType | 2 | String | One of: permanent, temporary, fixed-term, non-guaranteed-hours. |
| originalHireDate | 2 | Date | Original hire date in ISO 8601 format. |
| lastHireDate | 2 | Date | Most recent hire date (for rehires). |
| startDate | 2 | Date | Start date. |
| currentRoleStartDate | 2 | Date | Start date of current role. |
| currentGradeStartDate | 2 | Date | Start date of current grade. |
| terminationDate | 2 | Date | Termination date. |
| terminationReason | 2 | String | Reason for termination. |
| jobTitle | 2 | String | Job title, from the job profile. |
| businessTitle | 2 | String | Business title — a worker-level title that can differ from the job profile's job title. |
| jobCode | 2 | String | Job profile code. A string, so alphanumeric codes are supported. |
| jobLevel | 2 | String | Job level or band. |
| jobFamilyGroup | 2 | String | Job family group (the grouping above job family). |
| jobFamily | 2 | String | Job family or function. |
| workSchedule | 2 | Object | Work schedule details. |
| hoursPerWeek | 3 | Number | Hours per week. |
| workDays | 3 | String[] | Array of working days (e.g. ["Monday", "Tuesday"]). |
| isRemote | 3 | Boolean | Whether the employee works remotely. |
| hybridSchedule | 3 | String | Description of hybrid work arrangement. |
| eligibilityStatus | 2 | String | One of: verified, pending, not-verified. |
| workAuthorizationStatus | 2 | String | Work authorization status. |
| visa | 2 | Object | Visa information. |
| type | 3 | String | Visa type (e.g. "H1B", "O1"). |
| expirationDate | 3 | Date | Visa expiration date. |
| sponsorshipRequired | 3 | Boolean | Whether sponsorship is required. |
| department | 1 | String | Department. |
| division | 1 | String | Division. |
| team | 1 | String | Team. |
| costCenter | 1 | Object | Cost center. |
| id | 2 | String | Cost center code. |
| name | 2 | String | Cost center name. |
| companyName | 1 | String | Company or subsidiary name. |
| location | 1 | Object | Work location. |
| id | 2 | String | Location identifier. |
| name | 2 | String | Location name (e.g. "Sydney Office"). |
| address | 2 | Object | Location address (same structure as employee address). |
| isRemote | 2 | Boolean | Whether this is a remote location. |
| orgLevels | 1 | Object[] | Array of organizational hierarchy levels. |
| level | 2 | Number | Hierarchy level number. |
| name | 2 | String | Level name. |
| code | 2 | String | Level code. |
| groups | 1 | String[] | Array of group memberships. |
| manager | 1 | Object | Manager reference. |
| id | 2 | String | The employee id of the manager. |
| compensation | 1 | Object | Compensation details. |
| baseSalary | 2 | Number | Base salary amount. |
| currency | 2 | String | Currency code (e.g. "USD", "AUD"). |
| payFrequency | 2 | String | One of: hourly, weekly, bi-weekly, monthly, annually. |
| hourlyRate | 2 | Number | Hourly rate. |
| bonusTarget | 2 | Number | Bonus target amount. |
| bonusTargetPercentage | 2 | Number | Bonus target as a percentage. |
| commissionTarget | 2 | Number | Commission target amount. |
| commissionRate | 2 | Number | Commission rate. |
| totalCashCompensation | 2 | Number | Total cash compensation. |
| equityGrants | 2 | Object[] | Array of equity grants. |
| grantType | 3 | String | One of: stock-option, rsu, espp, phantom, other. |
| grantDate | 3 | Date | Grant date. |
| vestingStartDate | 3 | Date | Vesting start date. |
| vestingSchedule | 3 | String | Vesting schedule description. |
| vestingEndDate | 3 | Date | Vesting end date. |
| totalShares | 3 | Number | Total shares granted. |
| vestedShares | 3 | Number | Shares vested. |
| unvestedShares | 3 | Number | Shares not yet vested. |
| grantValue | 3 | Number | Value at grant. |
| currentValue | 3 | Number | Current value. |
| exercisePrice | 3 | Number | Exercise or strike price. |
| currency | 3 | String | Currency code. |
| benefitsEnrollment | 2 | String[] | Array of benefits enrolled in. |
| payGrade | 2 | String | Pay grade. |
| salaryRange | 2 | Object | Salary range for the pay grade. |
| min | 3 | Number | Minimum salary. |
| max | 3 | Number | Maximum salary. |
| midpoint | 3 | Number | Midpoint salary. |
| payChangeReason | 2 | String | Reason for last pay change. |
| lastReviewDate | 2 | Date | Date of last compensation review. |
| nextReviewDate | 2 | Date | Date of next compensation review. |
| performance | 1 | Object | Performance data. |
| rating | 2 | String | Performance rating label. |
| ratingNumeric | 2 | Number | Performance rating as a number. |
| reviewCycle | 2 | String | Review cycle name (e.g. "2025 Annual"). |
| reviewDate | 2 | Date | Date of review. |
| nextReviewDate | 2 | Date | Date of next review. |
| potentialRating | 2 | String | Potential rating label. |
| potentialRatingNumeric | 2 | Number | Potential rating as a number. |
| isHighPotential | 2 | Boolean | Whether employee is flagged as high potential. |
| isHighPerformer | 2 | Boolean | Whether employee is flagged as high performer. |
| goalAttainment | 2 | Number | Goal attainment percentage. |
| goalsSet | 2 | Number | Number of goals set. |
| goalsCompleted | 2 | Number | Number of goals completed. |
| competencyScores | 2 | Object[] | Array of competency assessments. |
| competencyName | 3 | String | Name of the competency. |
| score | 3 | Number | Score achieved. |
| rating | 3 | String | Rating label. |
| assessmentDate | 3 | Date | Date of assessment. |
| skills | 1 | Object[] | Array of skills. |
| name | 2 | String | Skill name. |
| category | 2 | String | Skill category. |
| proficiencyLevel | 2 | String | Proficiency level (e.g. "beginner", "intermediate", "advanced"). |
| proficiencyNumeric | 2 | Number | Proficiency as a number. |
| yearsOfExperience | 2 | Number | Years of experience with this skill. |
| source | 2 | String | One of: self-reported, manager-assessed, system-inferred, certification. |
| lastAssessedDate | 2 | Date | Date of last assessment. |
| certifications | 1 | Object[] | Array of certifications. |
| name | 2 | String | Certification name. |
| issuingOrganization | 2 | String | Issuing organization. |
| issueDate | 2 | Date | Date issued. |
| expirationDate | 2 | Date | Expiration date. |
| credentialId | 2 | String | Credential identifier. |
| status | 2 | String | One of: active, expired, pending-renewal. |
| languages | 1 | Object[] | Array of language proficiencies. |
| language | 2 | String | Language name. |
| proficiency | 2 | String | One of: basic, conversational, professional, native-or-bilingual. |
| isPreferred | 2 | Boolean | Whether this is the employee's preferred language. |
| trainingHoursYTD | 1 | Number | Training hours completed this year. |
| trainingHoursLastYear | 1 | Number | Training hours completed last year. |
| mandatoryTrainingComplete | 1 | Boolean | Whether mandatory training is complete. |
| developmentPlanStatus | 1 | String | One of: none, draft, active, completed. |
| leaveBalances | 1 | Object[] | Array of leave balances. |
| leaveType | 2 | String | Type of leave (e.g. "annual", "sick"). |
| entitled | 2 | Number | Leave entitled. |
| taken | 2 | Number | Leave taken. |
| remaining | 2 | Number | Leave remaining. |
| unit | 2 | String | One of: days, hours. |
| successionNominations | 1 | Object[] | Array of succession planning nominations. |
| targetId | 2 | String | The employee id of the target role holder. |
| targetJobTitle | 2 | String | Title of the target role. |
| readiness | 2 | String | One of: ready-now, ready-in-1-year, ready-in-2-plus-years, not-ready. |
| nominatedDate | 2 | Date | Date of nomination. |
| isCriticalRole | 1 | Boolean | Whether the employee holds a critical role. |
| flightRisk | 1 | String | One of: low, medium, high. |
| retentionPriority | 1 | String | One of: low, medium, high. |
| isManager | 1 | Boolean | Whether the employee is a manager. |
| isIndividualContributor | 1 | Boolean | Whether the employee is an individual contributor. |
| hiringSource | 1 | String | Where the employee was sourced (e.g. "referral", "job board"). |
| hiringSourceDetail | 1 | String | Additional detail about the hiring source. |
| referredBy | 1 | String | Name or id of the referrer. |
| applicationDate | 1 | Date | Application date. |
| offerDate | 1 | Date | Offer date. |
| timeToHire | 1 | Number | Days from application to hire. |
| timeToFill | 1 | Number | Days from requisition to hire. |
| interviewScore | 1 | Number | Interview score or rating. |
| hiringManagerRating | 1 | Number | Hiring manager rating. |
| events | 1 | Object[] | Array of employee lifecycle events. |
| eventType | 2 | String | One of: hire, rehire, termination, promotion, compensation-payout, leave-start, leave-end, other. |
| eventDate | 2 | Date | Date of the event. |
| effectiveDate | 2 | Date | Effective date of the event. |
| reason | 2 | String | Reason for the event. |
| payoutAmount | 2 | Number | Payout amount (for compensation-payout events). |
| payoutCurrency | 2 | String | Currency of the payout. |
| payoutType | 2 | String | One of: bonus, commission, equity, signing, retention, other. |
| details | 2 | Object | Additional event-specific details. |
| customFields | 1 | Object | Custom field values as key-value pairs. Keys must match defined Custom Field Definitions for the organization. Values are validated against the field type (string, number, boolean, date or enum). |
| lastUpdatedⁱ | 1 | Date | Timestamp of last update. |
| *=required. |
ⁱ=internal.
Custom Fields API
ENTERPRISE USERS
The Custom Fields API is only available to Enterprise and Partner accounts. Only organization Owners and Admins can access these endpoints.
The Custom Fields API enables you to define custom field schemas on your organization. These definitions control which custom fields can be set on employee records via the Employees API. Each definition specifies a key, display label, data type and optional constraints such as allowed enum values and whether the field is required.
GET /custom-fields
Retrieve all custom field definitions for the organization. By default, archived definitions are excluded.
Query Parameters:
| Name | Type | Description |
|---|---|---|
| includeArchived | Boolean | If set to true, includes archived definitions in results. Defaults to false. |
Response on Success:
An array of custom field definitions. See Format for Custom Field Definitions.
POST /custom-fields
Create a new custom field definition.
Body Parameters:
See Format for Custom Field Definitions. The key must start with a letter and contain only letters, numbers and underscores. The key must be unique within the organization — a 409 error is returned if a definition with the same key already exists. If the type is "enum", the enumValues array is required and must not be empty.
Response on Success:
PATCH /custom-fields/:key
Update an existing custom field definition. The key and type fields are immutable and cannot be changed — a 400 error is returned if an update to either is attempted.
URL Parameters:
| Name | Type | Description |
|---|---|---|
| key* | String | The custom field key identifier. Required. |
| *=required. |
Body Parameters:
Any subset of mutable fields from Format for Custom Field Definitions: label, description, category, required, enumValues (for enum type fields) and archived.
Response on Success:
See Format for Custom Field Definitions.
DELETE /custom-fields/:key
Archive a custom field definition (soft delete). The definition remains in the database but archived definitions cannot be used for new employee custom field values. Existing values on employees are not affected.
URL Parameters:
| Name | Type | Description |
|---|---|---|
| key* | String | The custom field key identifier. Required. |
| *=required. |
Response on Success:
204
Format for Custom Field Definitions
| Name | Level | Type | Description |
|---|---|---|---|
| key* | 1 | String | Unique identifier for the field. Must start with a letter and contain only letters, numbers and underscores. Immutable. |
| label* | 1 | String | Display label for the field. |
| type* | 1 | String | Data type. One of: string, number, boolean, date, enum. Immutable. |
| enumValues | 1 | String[] | Allowed values when type is "enum". Required if type is "enum". |
| required | 1 | Boolean | Whether employees must provide a value for this field. Defaults to false. |
| description | 1 | String | Description or help text for the field. |
| category | 1 | String | Category for grouping fields in the UI. |
| archivedⁱ | 1 | Boolean | Whether the definition is archived (soft-deleted). Defaults to false. |
| archivedAtⁱ | 1 | Date | Timestamp of when the definition was archived. |
| *=required. |
ⁱ=internal.