API

Overview

We make available an API to enable you to programmatically create, retrieve, update and delete your networks within Polinode. API access is available to all users with a Polinode account.

In order to access the API you will need to generate API credentials from within the Polinode web application. The Public Key is similar to a username and the Private Key should be treated as your password. Both should be stored securely. Polinode does not store your Private Key so be sure to record both your Public Key and Private Key and to store them securely prior to closing the dialogue. You can create up to 20 key pairs from within Polinode and can delete a key pair at any time.

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 HTTP Basic Access Authentication where your Public Key should be supplied as the username and your Private Key as the password. HTTP Basic Access Authentication is 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.

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.

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.

*=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.
  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.
  color 2 String The color to display the node in. Optional. Since you can color nodes by any attribute it is generally better to include the attribute that you want to color by under attributes. Though if you wanted every node to have a unique color you could do so here. If specified, color should be a rgba format string. For example, ‘rgba(120, 120, 120, 1)’.
  size 2 Number A number representing the relative size of nodes. Optional. Since you can size nodes by any attribute it is generally better to include the attribute that you want to size by under attributes.
  type 2 String The shape of the node. Optional, defaults to circle. Available options are: ‘circle’, ‘star’, ‘triangle’, ‘diamond’ and ‘square’.
  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.
    scale 3 Number Increase or decrease the size of the image. Useful when you have a square image from LinkedIn or Twitter say and would like to expand it to fill a circular node. Optional, the default is 1.3 for nodes without a type specified as they will be rendered as circles and 1 if a node type is specified.
    clip 3 Number Removes a portion of the image (from the edge of the image). Useful when you would like a border around the image after expanding the image using scale. Optional, the default is 0.85 for nodes without a type specified as they will be rendered as circles and 1 if a node type is specified.
  icon 2 Object Object encapsulating icon settings for a node below. Optional.
    font 3 String The name of the font to use for icons. There is currently only one option - ‘FontAwesome’ and this value is required if an icon is specified for the node.
    content 3 String The Unicode identifier for a Font Awesome icon to show at the center of the node. For a full list of available icons please visit this link. For example, to display an anchor you would enter ‘f13d’. Required if an icon is specified for the node.
    color 3 String The color of the icon displayed for a node in rgba format. Optional, the default is white, i.e. ‘rgba(255, 255, 255, 1)’.
    scale 3 Number Increase or decrease the size of the icon. Optional, the default is 1.
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.

*=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"
        }
      }
    ]
  };

Layouts API

ENTERPRISE USERS

The Layouts API is only available to Enterprise and Partner accounts.

POST /layouts/forceDirected

Runs the Yifan Hu force directed layout algorithm. One of either networkJSON, a networkId or a viewId must be provided. The layout algorithm will then be run on the provided network and node positions either returned or saved back to the network or view.

Node sizes will be taken into account if overlap is set to a value (such as false) that triggers overlap removal. The sizes of nodes can be set in the networkJSON as the size attribute on nodes (i.e. node.size). Alternatively, if a view sizes nodes by an attribute in a layer then those sizes will be used instead.

Compute time is limited to 30 seconds for each call.

Body Parameters:

Name Level Type Description
height 1 Number The desired height of the resuling layout. Defaults to 1000.
K 1 Number The spring constant used in the force directed layout algorithm. Increasing K tends to increase the distance between nodes. Defaults to 0.3 and must be greater than 0.
networkId* 1 String The Id of the network on which to run the layout algorithm. If provided, the network will be retrieved and the layout run. The resulting node positions will then be saved as x and y co-ordinates 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.
overlap 1 Boolean or String If true then overlaps between nodes are not removed. If false then overlaps are removed using a proximity graph-based algorithm called prism. The number of times this algorithm is run can also be controlled by setting a value explicity such as prism1, prism2, etc. By default the prism algorithm is run 1000 times (i.e. prism1000). The default value for this parameter is false.
pack 1 Number of String If true then each connected component in the network is laid out separately before being combined together with a fixed margin around each component. This margin may be varied by inputting a positive integer instead (e.g. 10). Alternatively, the entire graph will be laid out together if pack is false. Defaults to false.
ratio 1 Number or String The aspect ratio for the layout (i.e. height / width). Can be set to a number or, alternatively, the following strings can be provided: 'fill' (node positions are scaled separately in both x and y to fit the specified size) or 'expand' (node positions are scaled uniformly until at least one dimension fits size exactly). The default value is 'fill'.
repulsiveForce 1 Number The power of the repulsive force used in the force directed layout algorithm. Defaults to 0.9 and must be greater than 0.
sep 1 Number The margin to leave around nodes when removing overlap. Defaults to 0.
viewId* 1 String The Id of the view for which to run the layout algorithm. If provided, the network associated with that view will be retrieved and the layout run. The resulting node positions will then be saved as nodePositions for the provided view.
width 1 Number The desired width of the resuling layout. Defaults to 1000.

*One and only one of these three parameters must be provided.

Response on Success:

If networkJSON is provided directly then nodePositions are 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. If a viewId is provided then the result is saved directly as nodePositions for that view and a response of 200 is returned.

Lists API

ENTERPRISE USERS

The Lists API is only available to Enterprise and Partner accounts.

GET /lists

Retrieve all lists for a survey that the user has access to.

Query Parameters:

Name Level Type Description
surveyId 1 String The survey id of the survey to return lists for.

Response on Success:

An array of lists is returned with each element as per the Format for Lists. Note that nodes are not included in the response.

GET /lists/:id

Retrieve a specific list, including the nodes in that list.

URL Parameters:

Name Type Description
id* String The list id. Required.

*=required.

Response on Success:

See Format for Lists. Note that nodes are included in the response.

POST /lists

Create a new list.

Body Parameters:

See Format for Views. Body parameters must include required keys and should not include internal keys. Only Supplementary Lists or Previous Question lists can be created. Respondent Lists are automatically created when a survey is created and cannot be deleted. Nodes may be optionally included in the body of the request. Every node must include a name with additional keys / values interpreted as attributes for the node. Node names must be unique across each list.

Response on Success:

See Format for Views. Note that nodes are not included in the response.

PUT /lists/:id

Edit a previously created list. Use this route to add respondents to a respondent list.

URL Parameters:

Name Type Description
id* String The list id. Required.

*=required.

Body Parameters:

See Format for Lists. Body parameters must include required keys and should not include internal keys. Nodes may be optionally included in the body of the request. Every node must include a name with additional keys / values interpreted as attributes for the node. If the list type is a Respondent List then each node must also include an email. Name and email must be unique across each list. Additional keys / values will be interpreted as attributes. When updating a list nodes are NOT added incrementally. Rather, new nodes are added and, if a node no longer appears in the nodes array, then it is removed from the list. By default a check is performed on each list update and an error returned if nodes will be deleted from the list. To skip this check add 'skipCheckForDeletedNodes' and set it to 'yes'.

Response on Success:

See Format for Lists. Note that nodes are not included in the response.

DELETE /lists/:id

Delete a list. Note that Respondent Lists cannot be deleted.

URL Parameters:

Name Type Description
id* String The list id. Required.

*=required.

Response on Success:

200

Format for Lists

Name Level Type Description
_idⁱ 1 String The list id.
nodes 1 Object[] The items in the list, i.e. respondents or supplementary list items.
 _idⁱ 2 String The id of the node.
 attributes 2 Object[] Optional attributes for each node. Uploaded as simple key, values. Saved and returned with attribute names and string vs number values separated out.
 email 2 String The email of the node, for respondent lists
 lists 2 String[] An array with the id's of all the lists that this node appears in.
 name* 2 String The name of the node.
 survey 2 String The id of the survey that this node relates to
 type 2 String Either Respondent List or Supplementary List. If the node appears in the respondent list then will be Respondent List, else will be Supplementary List.
survey* 1 String The id of the survey that the list relates to.
title* 1 String The name of the list.
type* 1 String Either Respondent List, Supplementary List or Previous Question.

*=required.

ⁱ=internal.

Metrics API

ENTERPRISE USERS

The Metrics API is only available to Enterprise and Partner accounts.

Compute time for all metrics is limited to 30 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.

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/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 30 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 30 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.
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. Defaults to 1.

*One and only one of these two parameters must be provided.

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

Surveys API

ENTERPRISE USERS

The Surveys API is only available to Enterprise and Partner accounts.

GET /surveys

Retrieve all surveys for the user.

Parameters:

None

Response on Success:

An array of all the user’s surveys is returned with each element containing a survey as per Format for Surveys but excluding survey questions.

GET /surveys/:id

Retrieve a specific survey.

URL Parameters:

Name Type Description
id* String The survey id. Required.

*=required.

Response on Success:

See Format for Surveys.

POST /surveys

Create a new survey.

Body Parameters:

See Format for Surveys. Body parameters must include required keys and should not include internal keys.

Response on Success:

See Format for Surveys.

PUT /surveys/:id

Edit a previously created survey.

URL Parameters:

Name Type Description
id* String The survey id. Required.

*=required.

Body Parameters:

See Format for Surveys. Body parameters must include required keys and should not include internal keys.

Response on Success:

See Format for Surveys.

DELETE /surveys/:id

Delete a survey.

URL Parameters:

Name Type Description
id* String The survey id. Required.

*=required.

Response on Success:

200

PUT /surveys/clone/:id

Clones a survey in the user's account.

URL Parameters:

Name Type Description
id* String The survey id. Required.

*=required.

Body Parameters:

Name Level Type Description
newName* 1 String The name to use for the newly created survey.

*=required.

Response on Success:

See Format for Surveys. The newly created cloned survey is returned.

GET /surveys/users/:id

Retrieve a paged list of users with access to the survey.

URL Parameters:

Name Type Description
id* String The survey id. Required.

*=required.

Body Parameters:

Name Level Type Description
page 1 Number The page number for paged users. Defaults to 0.
perPage 1 Number The number of users to return per page. Defaults to 50.

Response on Success:

An array of users containing the user id, name, email, username, gravatarHash, isTempUser and permissions for the survey. Consistent with Format for Users.

POST /surveys/users/:id

Add a user to a survey with the provided permissions. The user requesting that another user be added must have permission to do so.

URL Parameters:

Name Type Description
id* String The survey id. Required.

*=required.

Body Parameters:

Name Level Type Description
email* 1 String The email of the user to add to the survey. Only users that already have an account should be added.
permission* 1 String Either 'Edit' or 'View'. The permission level that the user will have.
canAdd* 1 Boolean Whether the user can add other users to the survey.
canRemove* 1 Boolean Whether the user can remove other users from the survey.

*=required.

Response on Success:

200

PUT /surveys/users/:id/:userId

Update the permissions of a user for a survey. The requesting user must have the appropriate permissions themselves.

URL Parameters:

Name Type Description
id* String The survey id. Required.
userId* String The id of the user to be updated. Required.

*=required.

Body Parameters:

Name Level Type Description
permission* 1 String Either 'Edit' or 'View'. The permission level that the user should be updated to.
canAdd* 1 Boolean Whether the user can add other users to the survey.
canRemove* 1 Boolean Whether the user can remove other users from the survey.

*=required.

Response on Success:

200

DELETE /surveys/users/:id/:userId

Remove the user from the survey such that they will no longer have access. The requesting user must have the appropriate permissions themselves.

URL Parameters:

Name Type Description
id* String The survey id. Required.
userId* String The id of the user to be updated. Required.

*=required.

Response on Success:

200

GET /surveys/responseCounts/:id

Returns the number of responses by respondent status for the survey.

URL Parameters:

Name Type Description
id* String The survey id. Required.

*=required.

Response on Success:

An object with keys being the status type (e.g. Submitted, Bounced, etc.) and the values being the number of respondents with that status in the survey.

POST /surveys/testEmail/:id

Send a test email to a provided email address.

URL Parameters:

Name Type Description
id* String The survey id. Required.

*=required.

Body Parameters:

Name Level Type Description
to* 1 String The email address to send the email to.
body* 1 Boolean The body of the email. , and will be replaced with the unique values for the respondent and with test values here.
subject* 1 Boolean The subject of the email. , and will be replaced with the unique values for the respondent and with test values here.

*=required.

Response on Success:

200

POST /surveys/emailRespondents/:id

Email all respondents by status.

URL Parameters:

Name Type Description
id* String The survey id. Required.

*=required.

Body Parameters:

Name Level Type Description
sendEmailsData* 1 Object Contains the statuses to send emails to. If a status is not included emails will not be sent. Emails cannot be sent to the Opted Out status.
 Not Sent 2 Boolean If true then emails will be sent to respondents with the status Not Sent
 Not Started 2 Boolean If true then emails will be sent to respondents with the status Not Started
 Started 2 Boolean If true then emails will be sent to respondents with the status Started
 Submitted 2 Boolean If true then emails will be sent to respondents with the status Submitted
 Starred 2 Boolean If true then emails will be sent to respondents with the status Starred
 Bounced 2 Boolean If true then emails will be sent to respondents with the status Bounced
body* 1 Boolean The body of the email. , and will be replaced with the unique values for the respondent.
subject* 1 Boolean The subject of the email. , and will be replaced with the unique values for the respondent.

*=required.

Response on Success:

200

POST /surveys/generateNetworks/:id

Generate all networks for the survey. If networks have already been generatd then those networks will be updated, else new networks will be created. All users who have access to the survey will be granted access to the resulting networks with the same permissions. Depending on the size of the network it make take a few minutes for the networks to be generated and to appear in users' accounts.

URL Parameters:

Name Type Description
id* String The survey id. Required.

*=required.

Response on Success:

200

Format for Surveys

Please contact Polinode support for a copy of the data structure for Surveys.

Users API

ENTERPRISE USERS

The Users API is only available to Enterprise and Partner accounts.

TIP

Only users with Owner or Admin permission for an organisation may use the Users API.

GET /users

Retrieve all users for the organisation that the requesting user belongs to.

Response on Success:

An array of users is returned with each element containing:

  1. The Id of the user
  2. The email of the user
  3. Whether the user has completed sign-up or not (if isTempUser is true then the user has not completed signup)
  4. The maximum number of private networks the user may own (if set)
  5. The maximum number of public networks the user may own (if set)
  6. The name of the user
  7. The permission level of the user: either 'Owner', 'Admin', 'Standard User', 'Access-only' or 'Simplified Access-only'
  8. The number of private networks that the user currently is the Owner of
  9. The number of public networks that the user currently is the Owner of
  10. The username of the user

The array of users will be paged and a page parameter is accepted as a query parameter and a page number will be provided in the response.

GET /users/:id

Retrieve a specific user in the organisation.

URL Parameters:

Name Type Description
id* String The user id. Required.

*=required.

Response on Success:

See Format for users.

POST /users

Provision a new user for the organization.

Body Parameters:

The body parameters must contain email, name and permission. Permission may be any of 'Admin', 'Standard User', 'Access-only' or 'Simplified Access-only'. Optionally maxPublicNetworks, maxPrivateNetworks and/or maxRespondents may be provided as part of the body as well.

Response on Success:

The response will contain a summary of the user created with:

  1. The Id of the user
  2. The email of the user
  3. Gravatarhash for the user
  4. Whether the user has completed sign-up or not (if isTempUser is true then the user has not completed signup)
  5. The name of the user
  6. The permission level of the user: either 'Owner', 'Admin', 'Standard User', 'Access-only' or 'Simplified Access-only'
  7. The username of the user

PUT /users/:id

Edit a previously provisioned user.

URL Parameters:

Name Type Description
id* String The user id. Required.

*=required.

Body Parameters:

The body parameters may contain permission which may be any of 'Admin', 'Standard User', 'Access-only' or 'Simplified Access-only' and also may contain maxPublicNetworks, maxPrivateNetworks and/or maxRespondents.

Response on Success:

The response will contain a summary of the updated user with:

  1. The Id of the user
  2. The email of the user
  3. Gravatarhash for the user
  4. Whether the user has completed sign-up or not (if isTempUser is true then the user has not completed signup)
  5. The maximum private networks for the user
  6. The maxium public networks for the user
  7. The name of the user
  8. The permission level of the user: either 'Owner', 'Admin', 'Standard User', 'Access-only' or 'Simplified Access-only'
  9. The username of the user

DELETE /users/:id

Deprovision a user for the organisation.

URL Parameters:

Name Type Description
id* String The user id. Required.

*=required.

Response on Success:

200

POST /users/apiKeys

Create a set of API Keys for the user

Body Parameters:

Name Type Description
userId* String The id of the user to create the API keys for. Required.

*=required.

Response on Success:

A set of API keys, i.e JSON containing apiPrivateKey and apiPublicKey.

DELETE /users/apiKeys/:id

Delete a given API key for a user in the organisation.

Body Parameters:

Name Type Description
id* String The id of the apiPublicKey to be deleted

*=required.

Response on Success:

200

Format for Users

Name Level Type Description
_id 1 String The user id.
billing 1 Object An object containing billing information for the user.
 maxPrivateNetworks 2 Number The maximum number of private networks the user may own.
 maxPublicNetworks 2 Number The maximum number of public networks the user may own.
 networksSubscriptionType 2 String Will be 'enterprise' for all enterprise users.
 respondentCredits 2 String Not used for enterprise users as the respondent credits sit within the organization.
category 1 String Commercial, Non-Profit or Academic.
email 1 String The email address of the user.
features 1 Object Feature flags for the user.
 twoFactorAuth 2 Boolean Whether two factor auth may be used.
gravatarHash 1 String A unique identifier that may be used to retrieve the gravatar image for the user.
isTempUser 1 Boolean Wheter the user has completed sign-up or not (if isTempUser is true then the user has not completed signup).
name 1 String The name of the user.
networks 1 Object[] An array of objects containing the ids of the networks that the user has permission to access as well as the permissions that they have with respect to those networks.
organizations 1 Object[] An array containing a single objects with the organization id of the organization that the user is a member of as well as their permissions for that organization.
role 1 String Always 'User'.
surveys 1 String An array of objects containing the ids of the surveys that the user has permission to access as well as the permissions that they have with respect to those surveys.
suspended 1 Boolean True if the account has been suspended. False otherwise.
twoFactorAuth 1 Object Object containing the settings for two factor authentication.
 enabled 2 Boolean True if the user has activated two factor authentication. False otherwise.
username 1 String The username of the user. Temporarily set to the email address until the user completes signup.
verified 1 Boolean True if the user has verified their email address. False otherwise.

Views API

ENTERPRISE USERS

The Views API is only available to Enterprise and Partner accounts.

GET /views

Retrieve all views for a network or template views for a user.

Query Parameters:

Name Level Type Description
networkId 1 String The network id of the network to return views for. If no network id is supplied then the template views for the user will be returned.
page 1 Object Views will be paginated on return with 50 views per page. For more than 50 views (if relevant) a page number may be included.

Response on Success:

An array of views is returned with each element as per the Format for Views. Note that nodePositions are not included and that the page and total count of views for the query are also returned.

GET /views/:id

Retrieve a specific view, including the positions of nodes for that view.

URL Parameters:

Name Type Description
id* String The view id. Required.

*=required.

Response on Success:

See Format for Views. nodePositions is included in the response.

POST /views

Create a new view.

Body Parameters:

See Format for Views. Body parameters must include required keys and should not include internal keys.

Response on Success:

See Format for Views. Note that nodePositions is not included in the response.

PUT /views/:id

Edit a previously created view.

URL Parameters:

Name Type Description
id* String The view id. Required.

*=required.

Body Parameters:

See Format for Views. Body parameters must include required keys and should not include internal keys.

Response on Success:

See Format for Views. Note that nodePositions is not included in the response.

DELETE /views/:id

Delete a network.

URL Parameters:

Name Type Description
id* String The view id. Required.

*=required.

Response on Success:

200

Format for Views

Please contact Polinode support for a copy of the data structure for Views.

JSON Format for Node Positions

The format of node position data is JSON and is detailed below.

Node Positions JSON:

Name Level Type Description
[nodeId] 1 String The id of the node in the Network JSON.
  x 2 Number The x co-ordinate of the node.
  y 2 Number The y co-ordinate of the node.

Node Positions JSON Example:

{
	'Joe': {
		'x': 10,
		'y': 11
	},
	'Mary': {
		'x': 12,
		'y': 13
	},
	'Bill': {
		'x': 14,
		'y': 15
	},
	'Grant': {
		'x': 16,
		'y': 17
	}
}