Shell HTTP JavaScript Node.JS Ruby Python Java Go

Consents v0.2.4

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

The Consents API tracks a user's consent of financial institution policies and documents such as account terms and conditions, electronic consent, and privacy policy.

Target Documents

A consent resource holds the URI of a target document (typically, a PDF document). Each consent also has a type, such as privacyPolicy or termsAndConditions or electronicConsent, which indicates the target document's purpose and hence what kind of consent this is. The consent also holds the document's media type, specific document revision identification string, and the time stamp that the document was last revised (modified). If the document is later revised, any previously given consents for any revision of that document become stale; this indicates the user should review and consent to the revised document.

Contexts

A consent may be associated with a context in which an application or service is requesting the consent; the context is represented as the URI of some resource. For example, two different banking products (DDA1, DDA2) at a financial institution may share the same terms and conditions document, D0. If the user is opening an account of type DDA1, the client can create a consent for D0 using the product URI for DDA1 as the context. When the user opens a new account for product DDA2, the client can create a new consent for D0 using product DDA2's URI as the context. Because the contexts of the two consents are different, the two consents are independent of each other, indicating that the user must consent to the terms and conditions each time they open an account, even if they have consented to the same document earlier.

The context is optional. For example, for the financial institution's privacy policy, there is no specific context.

Life Cycle

When a banking application or service (the requester) wishes a user to agree to or consent to a document, it creates a new consent resource (POST /consents) to track the request and the user's response.

The user can consent to a document to indicate that they agree to the terms described in the document. This is typically done when the user checks an "I agree" checkbox or other user experience. To record the consent given by the user, the client application which serves as the controller issues a POST to the apiture:give link on a consent resource. This sets the state to given and records the date and time on the consent.

When a user gives consent to a document, all consent resources which match the target document, context URI, and user ID are also marked as given, although the action can be scoped to just a specific instance.

A client can check for pending or stale consents for a user with the GET /neededConsents operation.

Consents are not directly mutable (the PUT and PATCH verbs are not supported), but other operations described below may update a consent resource to indicate a user has given or revoked consent, that a consent is stale, or that a requester has rescinded a request for consent.

If the user wishes to undo or revoke a specific consent, the client application should POST to the apiture:revoke link on a consent resource (/revokedConsents?consent={consentId}) to reset the consent back to the pending state.

If the requester no longer requires the user's consent, it can rescind the request with POST /rescindedConsents?type={type}?document={documentUri}?context={contextUri}?user=user This sets the state to rescinded on the first matching consent. For example, if the user is removed as a joint owner of an account of type DDA2, rescinding the termsAndConditions consents will match and remove only the first matching consent for DDA2. (The user may be an owner of other accounts on product DDA2, and their consent must be tracked and possibly requested again if the terms and conditions for DDA2 change.)

Document revisions

If the document is revised (for example, the financial institution has updated their privacy policy), a client can mark a document as revised via POST /revisedDocuments. All consents associated with the older revisions of the document are marked stale. A stale consent indicates that the user should consent to the revised document. The client applications should notify the user that the document has changed (such as via email or or via notification at their next login) and present the revised document to the user for them to accept.

Download OpenAPI Definition (YAML)

Base URLs:

Terms of service

Email: Apiture Web: Apiture

Authentication

Scope Scope Description
banking/read Read access to things
banking/write Write (update) access to things
banking/delete Delete access to things
banking/full Full access to things

API

Endpoints which describe this API

getApi

Code samples

# You can also use wget
curl -X GET /consents/ \
  -H 'Accept: application/hal+json' \
  -H 'API-Key: API_KEY'

GET /consents/ HTTP/1.1

Accept: application/hal+json

var headers = {
  'Accept':'application/hal+json',
  'API-Key':'API_KEY'

};

$.ajax({
  url: '/consents/',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/hal+json',
  'API-Key':'API_KEY'

};

fetch('/consents/',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/hal+json',
  'API-Key' => 'API_KEY'
}

result = RestClient.get '/consents/',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/hal+json',
  'API-Key': 'API_KEY'
}

r = requests.get('/consents/', params={

}, headers = headers)

print r.json()

URL obj = new URL("/consents/");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/hal+json"},
        "API-Key": []string{"API_KEY"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "/consents/", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

Top-level resources and operations in this API

GET /

Return links to the top-level resources and operations in this API.

Example responses

200 Response

{
  "id": "apiName",
  "name": "API name",
  "apiVersion": "1.0.0",
  "_profile": "https://api.apiture.com/schemas/common/root/v1.0.0/profile.json",
  "_links": {}
}

Responses

StatusDescription
200 OK
OK
Schema: root

getApiDoc

Code samples

# You can also use wget
curl -X GET /consents/apiDoc \
  -H 'Accept: application/json' \
  -H 'API-Key: API_KEY'

GET /consents/apiDoc HTTP/1.1

Accept: application/json

var headers = {
  'Accept':'application/json',
  'API-Key':'API_KEY'

};

$.ajax({
  url: '/consents/apiDoc',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'API-Key':'API_KEY'

};

fetch('/consents/apiDoc',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'API-Key' => 'API_KEY'
}

result = RestClient.get '/consents/apiDoc',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'API-Key': 'API_KEY'
}

r = requests.get('/consents/apiDoc', params={

}, headers = headers)

print r.json()

URL obj = new URL("/consents/apiDoc");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "API-Key": []string{"API_KEY"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "/consents/apiDoc", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

Return API definition document

GET /apiDoc

Return the OpenAPI document that describes this API.

Example responses

200 Response

{}

Responses

StatusDescription
200 OK
OK
Schema: Inline

Response Schema

Consent

User consent of a policy or other document

getConsents

Code samples

# You can also use wget
curl -X GET /consents/consents \
  -H 'Accept: application/hal+json' \
  -H 'API-Key: API_KEY' \
  -H 'Authorization: Bearer {access-token}'

GET /consents/consents HTTP/1.1

Accept: application/hal+json

var headers = {
  'Accept':'application/hal+json',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: '/consents/consents',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/hal+json',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

fetch('/consents/consents',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/hal+json',
  'API-Key' => 'API_KEY',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get '/consents/consents',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/hal+json',
  'API-Key': 'API_KEY',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('/consents/consents', params={

}, headers = headers)

print r.json()

URL obj = new URL("/consents/consents");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/hal+json"},
        "API-Key": []string{"API_KEY"},
        "Authorization": []string{"Bearer {access-token}"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "/consents/consents", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

Return a collection of consents

GET /consents

Return a paginated sortable filterable searchable collection of consents. The links in the response include pagination links.

Parameters

Parameter Description
type
(query)
string
Subset the response to those with this type value. Use | to separate multiple values. For example, ?type=termsAndCondition will match only items whose type is termsAndCondition ?type=privacyPolicy|electronicConsent will match items whose type is privacyPolicy or electronicConsent. This is combined with an implicit and with other filters if they are used. See filtering.
state
(query)
string
Subset the response to those with this state value. Use | to separate multiple values. For example, ?type=given|stale will match only items whose state is given or stale. This is combined with an implicit and with other filters if they are used. See filtering.
userId
(query)
string
Subset the response to those with this userId value. Use | to separate multiple values. This is for administrative use; bank users can only see their own consents.
contextUri
(query)
string
Subset the response to those with this contextUri value. Use | to separate multiple values.
start
(query)
integer(int64)
The zero-based index of the first consent item to include in this page. The default 0 denotes the beginning of the collection.
limit
(query)
integer(int32)
The maximum number of consent representations to return in this page.
sortBy
(query)
string
Optional sort criteria. See sort criteria format, such as ?sortBy=field1,-field2.
filter
(query)
string
Optional filter criteria. See filtering.
q
(query)
string
Optional search string. See searching.

Example responses

200 Response

{
  "_profile": "https://api.apiture.com/schemas/consents/consents/v1.0.0/profile.json",
  "start": 10,
  "limit": 10,
  "count": 67,
  "name": "consents",
  "_links": {
    "self": {
      "href": "/consents/consents?start=10&limit=10"
    },
    "first": {
      "href": "/consents/consents?start=0&limit=10"
    },
    "next": {
      "href": "/consents/consents?start=20&limit=10"
    },
    "collection": {
      "href": "/consents/consents"
    }
  },
  "_embedded": {
    "items": [
      {
        "_id": "0399abed-fd3d-4830-a88b-30f38b8a365c",
        "_profile": "https://api.apiture.com/schemas/consents/consent/v1.0.0/profile.json",
        "_links": {
          "self": {
            "href": "/consents/consents/0399abed-fd3d-4830-a88b-30f38b8a365c"
          }
        }
      },
      {
        "_id": "d62c0701-0d74-4836-83f9-ebf3709442ea",
        "_profile": "https://api.apiture.com/schemas/consents/consent/v1.0.0/profile.json",
        "_links": {
          "self": {
            "href": "/consents/consents/d62c0701-0d74-4836-83f9-ebf3709442ea"
          }
        }
      }
    ]
  }
}

Responses

StatusDescription
200 OK
OK
Schema: consents
400 Bad Request
Bad Request. The request body or one or more of the query parameters was not well formed. The _error field in the response will contain details about the request error.
Schema: errorResponse
422 Unprocessable Entity
Unprocessable Entity. One or more of the query parameters was well formed but otherwise invalid. The _error field in the response will contain details about the request error.
Schema: errorResponse

createConsent

Code samples

# You can also use wget
curl -X POST /consents/consents \
  -H 'Content-Type: application/hal+json' \
  -H 'Accept: application/hal+json' \
  -H 'API-Key: API_KEY' \
  -H 'Authorization: Bearer {access-token}'

POST /consents/consents HTTP/1.1

Content-Type: application/hal+json
Accept: application/hal+json

var headers = {
  'Content-Type':'application/hal+json',
  'Accept':'application/hal+json',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: '/consents/consents',
  method: 'post',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');
const inputBody = '{
  "_profile": "https://api.apiture.com/schemas/consents/createConsent/v1.0.0/profile.json",
  "document": {
    "uri": "/vault/files/fd44d565-0086-4caf-8d9f-3b7681809251/content",
    "contentType": "application/pdf",
    "revisionId": "2019:1.02.0",
    "revisedAt": "2019-07-23T08:26:45.375Z"
  },
  "type": "termsAndConditions",
  "userId": "5a5e834c-a7bd-401c",
  "contextUri": "/products/products/34011fe5-192d-4ffb-be32-e7215e56028a"
}';
const headers = {
  'Content-Type':'application/hal+json',
  'Accept':'application/hal+json',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

fetch('/consents/consents',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/hal+json',
  'Accept' => 'application/hal+json',
  'API-Key' => 'API_KEY',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post '/consents/consents',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/hal+json',
  'Accept': 'application/hal+json',
  'API-Key': 'API_KEY',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('/consents/consents', params={

}, headers = headers)

print r.json()

URL obj = new URL("/consents/consents");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/hal+json"},
        "Accept": []string{"application/hal+json"},
        "API-Key": []string{"API_KEY"},
        "Authorization": []string{"Bearer {access-token}"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "/consents/consents", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

Create a new consent

POST /consents

Create a new consent resource.

Body parameter

{
  "_profile": "https://api.apiture.com/schemas/consents/createConsent/v1.0.0/profile.json",
  "document": {
    "uri": "/vault/files/fd44d565-0086-4caf-8d9f-3b7681809251/content",
    "contentType": "application/pdf",
    "revisionId": "2019:1.02.0",
    "revisedAt": "2019-07-23T08:26:45.375Z"
  },
  "type": "termsAndConditions",
  "userId": "5a5e834c-a7bd-401c",
  "contextUri": "/products/products/34011fe5-192d-4ffb-be32-e7215e56028a"
}

Parameters

Parameter Description
body
(body)
createConsent (required)
The data necessary to create a new consent.

Example responses

200 Response

{
  "_id": "0399abed-fd3d-4830-a88b-30f38b8a365c",
  "_profile": "https://api.apiture.com/schemas/consents/consent/v1.0.0/profile.json",
  "document": {
    "uri": "/vault/files/fd44d565-0086-4caf-8d9f-3b7681809251/content",
    "contentType": "application/pdf",
    "revisionId": "2019:1.02.0",
    "revisedAt": "2019-07-23T08:26:45.375Z"
  },
  "state": "given",
  "givenAt": "2019-07-23T13:27:34.375Z",
  "type": "termsAndConditions",
  "userId": "5a5e834c-a7bd-401c",
  "contextUri": "/products/products/34011fe5-192d-4ffb-be32-e7215e56028a",
  "_links": {
    "self": {
      "href": "/consents/consents/0399abed-fd3d-4830-a88b-30f38b8a365c"
    },
    "apiture:revoke": {
      "href": "/consents/revokedConsents?consent=0399abed-fd3d-4830-a88b-30f38b8a365c"
    },
    "apiture:rescind": {
      "href": "/consents/rescindedConsents?consent=0399abed-fd3d-4830-a88b-30f38b8a365c"
    }
  }
}

Responses

StatusDescription
200 OK
OK. An existing consent resource for the document and user was found and the contextUri of this request added to that resource.
Schema: consent
201 Created
Created
Schema: consent
400 Bad Request
Bad Request. The request body or content was not well formed.
Schema: errorResponse

Response Headers

StatusDescription
200 Location string uri
The URI of the existing consent resource. If the URI begins with / it is relative to the API root context. Else, it is a full URI starting with scheme://host
200 ETag string
The ETag response header specifies an entity tag which must be provided in an If-Match request header for operations which update the resource.
201 Location string uri
The URI of the new resource. If the URI begins with / it is relative to the API root context. Else, it is a full URI starting with scheme://host
201 ETag string
The ETag response header specifies an entity tag which must be provided in an If-Match request header for operations which update the resource.

getConsent

Code samples

# You can also use wget
curl -X GET /consents/consents/{consentId} \
  -H 'Accept: application/hal+json' \
  -H 'If-None-Match: string' \
  -H 'API-Key: API_KEY' \
  -H 'Authorization: Bearer {access-token}'

GET /consents/consents/{consentId} HTTP/1.1

Accept: application/hal+json
If-None-Match: string

var headers = {
  'Accept':'application/hal+json',
  'If-None-Match':'string',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: '/consents/consents/{consentId}',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/hal+json',
  'If-None-Match':'string',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

fetch('/consents/consents/{consentId}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/hal+json',
  'If-None-Match' => 'string',
  'API-Key' => 'API_KEY',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get '/consents/consents/{consentId}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/hal+json',
  'If-None-Match': 'string',
  'API-Key': 'API_KEY',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('/consents/consents/{consentId}', params={

}, headers = headers)

print r.json()

URL obj = new URL("/consents/consents/{consentId}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/hal+json"},
        "If-None-Match": []string{"string"},
        "API-Key": []string{"API_KEY"},
        "Authorization": []string{"Bearer {access-token}"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "/consents/consents/{consentId}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

Fetch a representation of this consent

GET /consents/{consentId}

Return a HAL representation of this consent resource.

Parameters

Parameter Description
consentId
(path)
string (required)
The unique identifier of this consent. This is an opaque string.
If-None-Match
(header)
string
The entity tag that was returned in the ETag response. If the resource's current entity tag matches, the GET will return 304 (Not Modified) and no response body, else the resource representation will be returned.

Example responses

200 Response

{
  "_id": "0399abed-fd3d-4830-a88b-30f38b8a365c",
  "_profile": "https://api.apiture.com/schemas/consents/consent/v1.0.0/profile.json",
  "document": {
    "uri": "/vault/files/fd44d565-0086-4caf-8d9f-3b7681809251/content",
    "contentType": "application/pdf",
    "revisionId": "2019:1.02.0",
    "revisedAt": "2019-07-23T08:26:45.375Z"
  },
  "state": "given",
  "givenAt": "2019-07-23T13:27:34.375Z",
  "type": "termsAndConditions",
  "userId": "5a5e834c-a7bd-401c",
  "contextUri": "/products/products/34011fe5-192d-4ffb-be32-e7215e56028a",
  "_links": {
    "self": {
      "href": "/consents/consents/0399abed-fd3d-4830-a88b-30f38b8a365c"
    },
    "apiture:revoke": {
      "href": "/consents/revokedConsents?consent=0399abed-fd3d-4830-a88b-30f38b8a365c"
    },
    "apiture:rescind": {
      "href": "/consents/rescindedConsents?consent=0399abed-fd3d-4830-a88b-30f38b8a365c"
    }
  }
}

Responses

StatusDescription
200 OK
OK
Schema: consent
304 Not Modified
Not Modified. The resource has not been modified since it was last fetched.
404 Not Found
Not Found. There is no such consent resource at the specified {consentId}. The _error field in the response will contain details about the request error.
Schema: errorResponse

Response Headers

StatusDescription
200 ETag string
The ETag response header specifies an entity tag which must be provided in an If-Match request header for operations which update this consent resource.

getNeededConsents

Code samples

# You can also use wget
curl -X GET /consents/neededConsents \
  -H 'Accept: application/hal+json' \
  -H 'API-Key: API_KEY' \
  -H 'Authorization: Bearer {access-token}'

GET /consents/neededConsents HTTP/1.1

Accept: application/hal+json

var headers = {
  'Accept':'application/hal+json',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: '/consents/neededConsents',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/hal+json',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

fetch('/consents/neededConsents',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/hal+json',
  'API-Key' => 'API_KEY',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get '/consents/neededConsents',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/hal+json',
  'API-Key': 'API_KEY',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('/consents/neededConsents', params={

}, headers = headers)

print r.json()

URL obj = new URL("/consents/neededConsents");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/hal+json"},
        "API-Key": []string{"API_KEY"},
        "Authorization": []string{"Bearer {access-token}"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "/consents/neededConsents", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

Get needed consents

GET /neededConsents

Return a list of needed consents (both pending and stale consents) for a user. If no consents exists for a user ID (including if the user ID is not found), the response is an empty collection.

Parameters

Parameter Description
userId
(query)
string
The user ID of the user; This is the _id of the User resource. If omitted, the returned list is the needed consents for the currently authenticated user.

Example responses

200 Response

{
  "_profile": "https://api.apiture.com/schemas/consents/consents/v1.0.0/profile.json",
  "start": 10,
  "limit": 10,
  "count": 67,
  "name": "consents",
  "_links": {
    "self": {
      "href": "/consents/consents?start=10&limit=10"
    },
    "first": {
      "href": "/consents/consents?start=0&limit=10"
    },
    "next": {
      "href": "/consents/consents?start=20&limit=10"
    },
    "collection": {
      "href": "/consents/consents"
    }
  },
  "_embedded": {
    "items": [
      {
        "_id": "0399abed-fd3d-4830-a88b-30f38b8a365c",
        "_profile": "https://api.apiture.com/schemas/consents/consent/v1.0.0/profile.json",
        "_links": {
          "self": {
            "href": "/consents/consents/0399abed-fd3d-4830-a88b-30f38b8a365c"
          }
        }
      },
      {
        "_id": "d62c0701-0d74-4836-83f9-ebf3709442ea",
        "_profile": "https://api.apiture.com/schemas/consents/consent/v1.0.0/profile.json",
        "_links": {
          "self": {
            "href": "/consents/consents/d62c0701-0d74-4836-83f9-ebf3709442ea"
          }
        }
      }
    ]
  }
}

Responses

StatusDescription
200 OK
OK.
Schema: consents

reviseDocument

Code samples

# You can also use wget
curl -X POST /consents/revisedDocuments \
  -H 'Content-Type: application/hal+json' \
  -H 'Accept: application/hal+json' \
  -H 'API-Key: API_KEY' \
  -H 'Authorization: Bearer {access-token}'

POST /consents/revisedDocuments HTTP/1.1

Content-Type: application/hal+json
Accept: application/hal+json

var headers = {
  'Content-Type':'application/hal+json',
  'Accept':'application/hal+json',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: '/consents/revisedDocuments',
  method: 'post',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');
const inputBody = '{
  "_profile": "https://api.apiture.com/schemas/consents/revisedDocument/v1.0.0/profile.json",
  "uri": "/vault/files/fd44d565-0086-4caf-8d9f-3b7681809251/content",
  "revisionId": "2019:1.2.0",
  "contextUri": "/products/products/34011fe5-192d-4ffb-be32-e7215e56028a",
  "revisedAt": "2019-10-05T10:30:00.000Z",
  "type": "termsAndConditions",
  "newUri": "/vault/files/da66d490-2b72-4809-9b97-9b33039371f8/content"
}';
const headers = {
  'Content-Type':'application/hal+json',
  'Accept':'application/hal+json',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

fetch('/consents/revisedDocuments',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/hal+json',
  'Accept' => 'application/hal+json',
  'API-Key' => 'API_KEY',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post '/consents/revisedDocuments',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/hal+json',
  'Accept': 'application/hal+json',
  'API-Key': 'API_KEY',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('/consents/revisedDocuments', params={

}, headers = headers)

print r.json()

URL obj = new URL("/consents/revisedDocuments");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/hal+json"},
        "Accept": []string{"application/hal+json"},
        "API-Key": []string{"API_KEY"},
        "Authorization": []string{"Bearer {access-token}"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "/consents/revisedDocuments", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

Mark a document as revised, rendering corresponding consents as stale

POST /revisedDocuments

Mark a document as revised. All given consents related to that document, document type, and the optional context are marked as stale, indicating that the user should be presented the document and asked to consent to the terms of the revised document. The newly stale consents will now be listed in the result of GET /neededConsents. This operation is restricted to financial institution administrators or service applications. Any given consents which already match the document and time stamp (and, optionally, document revision) are not marked stale.

Body parameter

{
  "_profile": "https://api.apiture.com/schemas/consents/revisedDocument/v1.0.0/profile.json",
  "uri": "/vault/files/fd44d565-0086-4caf-8d9f-3b7681809251/content",
  "revisionId": "2019:1.2.0",
  "contextUri": "/products/products/34011fe5-192d-4ffb-be32-e7215e56028a",
  "revisedAt": "2019-10-05T10:30:00.000Z",
  "type": "termsAndConditions",
  "newUri": "/vault/files/da66d490-2b72-4809-9b97-9b33039371f8/content"
}

Parameters

Parameter Description
body
(body)
revisedDocument (required)
The details of the revised document.

Example responses

202 Response

{
  "_profile": "https://api.apiture.com/schemas/consents/revisedDocument/v1.0.0/profile.json",
  "uri": "/vault/files/fd44d565-0086-4caf-8d9f-3b7681809251/content",
  "revisionId": "2019:1.2.0",
  "contextUri": "/products/products/34011fe5-192d-4ffb-be32-e7215e56028a",
  "revisedAt": "2019-10-05T10:30:00.000Z",
  "type": "termsAndConditions",
  "newUri": "/vault/files/da66d490-2b72-4809-9b97-9b33039371f8/content"
}

Responses

StatusDescription
202 Accepted
Accepted. The operation was received and accepted. The operation will continue to update all matching consents, setting state changed to stale and changing the revision and documentRevisedAt to match the values in the request.
Schema: revisedDocument
400 Bad Request
Bad Request. The request body or content was not well formed.
Schema: errorResponse
409 Conflict
Conflict. The request contains semantically invalid data.
Schema: errorResponse
412 Precondition Failed
Precondition Failed. The supplied If-Match header value does not match the most recent ETag response header value. The resource has changed in the interim.
Schema: errorResponse

giveConsent

Code samples

# You can also use wget
curl -X POST /consents/givenConsents?consent=string \
  -H 'Accept: application/hal+json' \
  -H 'API-Key: API_KEY' \
  -H 'Authorization: Bearer {access-token}'

POST /consents/givenConsents?consent=string HTTP/1.1

Accept: application/hal+json

var headers = {
  'Accept':'application/hal+json',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: '/consents/givenConsents',
  method: 'post',
  data: '?consent=string',
  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/hal+json',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

fetch('/consents/givenConsents?consent=string',
{
  method: 'POST',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/hal+json',
  'API-Key' => 'API_KEY',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post '/consents/givenConsents',
  params: {
  'consent' => 'string'
}, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/hal+json',
  'API-Key': 'API_KEY',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('/consents/givenConsents', params={
  'consent': 'string'
}, headers = headers)

print r.json()

URL obj = new URL("/consents/givenConsents?consent=string");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/hal+json"},
        "API-Key": []string{"API_KEY"},
        "Authorization": []string{"Bearer {access-token}"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "/consents/givenConsents", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

Give a consent

POST /givenConsents

Indicate that a user has given consent to a document. This marks the the given consent as given. If scope is matching, all matching needed consents (pending or stale consents which have the same type, document.uri and contextUri) will also be marked as given. This operation may be invoked by using POST on the apiture:giveConsent link on a consent resource; there is no query parameter.

Parameters

Parameter Description
consent
(query)
string (required)
A string which uniquely identifies a consent which is to added to the given consents resource set. This may be the unique consentId or the URI of the consent.
scope
(query)
string
The scope of the given consent. If instance, only the consent named in the ?consent= query parameter is marked as given. If matching, all needed consent matching the named in the ?consent= query parameter (pending or stale consents which have the same type, document.uri and contextUri) are marked as given. The default if omitted is matching.
Enumerated values:
instance
matching

Example responses

200 Response

{
  "_id": "0399abed-fd3d-4830-a88b-30f38b8a365c",
  "_profile": "https://api.apiture.com/schemas/consents/consent/v1.0.0/profile.json",
  "document": {
    "uri": "/vault/files/fd44d565-0086-4caf-8d9f-3b7681809251/content",
    "contentType": "application/pdf",
    "revisionId": "2019:1.02.0",
    "revisedAt": "2019-07-23T08:26:45.375Z"
  },
  "state": "given",
  "givenAt": "2019-07-23T13:27:34.375Z",
  "type": "termsAndConditions",
  "userId": "5a5e834c-a7bd-401c",
  "contextUri": "/products/products/34011fe5-192d-4ffb-be32-e7215e56028a",
  "_links": {
    "self": {
      "href": "/consents/consents/0399abed-fd3d-4830-a88b-30f38b8a365c"
    },
    "apiture:revoke": {
      "href": "/consents/revokedConsents?consent=0399abed-fd3d-4830-a88b-30f38b8a365c"
    },
    "apiture:rescind": {
      "href": "/consents/rescindedConsents?consent=0399abed-fd3d-4830-a88b-30f38b8a365c"
    }
  }
}

Responses

StatusDescription
200 OK
OK. The operation succeeded. The consents were updated and their state changed to given. The response may include an array of additional consents _embedded.consents which match the named consent and which were also given.
Schema: consent
400 Bad Request
Bad Request. The consent parameter was malformed or does not refer to an existing or accessible consent.
Schema: errorResponse
409 Conflict
Conflict. The request to give the consent is not allowed. The _error field in the response will contain details about the request error. For example, the consent may have been revoked or rescinded.
412 Precondition Failed
Precondition Failed. The supplied If-Match header value does not match the most recent ETag response header value. The resource has changed in the interim.
Schema: errorResponse

revokeConsent

Code samples

# You can also use wget
curl -X POST /consents/revokedConsents?consent=string \
  -H 'Accept: application/hal+json' \
  -H 'If-Match: string' \
  -H 'API-Key: API_KEY' \
  -H 'Authorization: Bearer {access-token}'

POST /consents/revokedConsents?consent=string HTTP/1.1

Accept: application/hal+json
If-Match: string

var headers = {
  'Accept':'application/hal+json',
  'If-Match':'string',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: '/consents/revokedConsents',
  method: 'post',
  data: '?consent=string',
  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/hal+json',
  'If-Match':'string',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

fetch('/consents/revokedConsents?consent=string',
{
  method: 'POST',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/hal+json',
  'If-Match' => 'string',
  'API-Key' => 'API_KEY',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post '/consents/revokedConsents',
  params: {
  'consent' => 'string'
}, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/hal+json',
  'If-Match': 'string',
  'API-Key': 'API_KEY',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('/consents/revokedConsents', params={
  'consent': 'string'
}, headers = headers)

print r.json()

URL obj = new URL("/consents/revokedConsents?consent=string");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/hal+json"},
        "If-Match": []string{"string"},
        "API-Key": []string{"API_KEY"},
        "Authorization": []string{"Bearer {access-token}"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "/consents/revokedConsents", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

Revoke a consent

POST /revokedConsents

Update a consent by adding it to the set of revoked consents. This changes the state property of the consent to revoked. This operation is available via the apiture:revoke link on the consent resource, if and only if the consent is eligible for the revoke operation. The responses is the updated representation of the consent. The If-Match request header value must match the current entity tag value of the consent.

Parameters

Parameter Description
consent
(query)
string (required)
A string which uniquely identifies a consent which is to added to the given consents resource set. This may be the unique consentId or the URI of the consent.
If-Match
(header)
string
The entity tag that was returned in the ETag response. This must match the current entity tag of the resource.

Example responses

200 Response

{
  "_id": "0399abed-fd3d-4830-a88b-30f38b8a365c",
  "_profile": "https://api.apiture.com/schemas/consents/consent/v1.0.0/profile.json",
  "document": {
    "uri": "/vault/files/fd44d565-0086-4caf-8d9f-3b7681809251/content",
    "contentType": "application/pdf",
    "revisionId": "2019:1.02.0",
    "revisedAt": "2019-07-23T08:26:45.375Z"
  },
  "state": "given",
  "givenAt": "2019-07-23T13:27:34.375Z",
  "type": "termsAndConditions",
  "userId": "5a5e834c-a7bd-401c",
  "contextUri": "/products/products/34011fe5-192d-4ffb-be32-e7215e56028a",
  "_links": {
    "self": {
      "href": "/consents/consents/0399abed-fd3d-4830-a88b-30f38b8a365c"
    },
    "apiture:revoke": {
      "href": "/consents/revokedConsents?consent=0399abed-fd3d-4830-a88b-30f38b8a365c"
    },
    "apiture:rescind": {
      "href": "/consents/rescindedConsents?consent=0399abed-fd3d-4830-a88b-30f38b8a365c"
    }
  }
}

Responses

StatusDescription
200 OK
OK. The operation succeeded. The consent was updated and its state changed to revoked.
Schema: consent
400 Bad Request
Bad Request. The consent parameter was malformed or does not refer to an existing or accessible consent.
Schema: errorResponse
409 Conflict
Conflict. The request to revoke the consent is not allowed. The _error field in the response will contain details about the request error.
412 Precondition Failed
Precondition Failed. The supplied If-Match header value does not match the most recent ETag response header value. The resource has changed in the interim.
Schema: errorResponse

Response Headers

StatusDescription
200 ETag string
The ETag response header specifies an entity tag which must be provided in an If-Match request header for operations which update the resource.

rescindConsents

Code samples

# You can also use wget
curl -X POST /consents/rescindedConsents?type=string&context=string&user=string \
  -H 'Accept: application/hal+json' \
  -H 'API-Key: API_KEY' \
  -H 'Authorization: Bearer {access-token}'

POST /consents/rescindedConsents?type=string&context=string&user=string HTTP/1.1

Accept: application/hal+json

var headers = {
  'Accept':'application/hal+json',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: '/consents/rescindedConsents',
  method: 'post',
  data: '?type=string&context=string&user=string',
  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/hal+json',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

fetch('/consents/rescindedConsents?type=string&context=string&user=string',
{
  method: 'POST',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/hal+json',
  'API-Key' => 'API_KEY',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post '/consents/rescindedConsents',
  params: {
  'type' => 'string',
'context' => 'string(url)',
'user' => 'string(url)'
}, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/hal+json',
  'API-Key': 'API_KEY',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('/consents/rescindedConsents', params={
  'type': 'string',  'context': 'string',  'user': 'string'
}, headers = headers)

print r.json()

URL obj = new URL("/consents/rescindedConsents?type=string&context=string&user=string");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/hal+json"},
        "API-Key": []string{"API_KEY"},
        "Authorization": []string{"Bearer {access-token}"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "/consents/rescindedConsents", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

Rescind matching consents

POST /rescindedConsents

Rescind consent requests which match the specified consent type, context, and user. This changes the state property of the matching consents to rescinded. The client must pass the type, context, and user in order to find matching consents; if the document is also specified, it must also match.

The response is the collection of updated consent resources. If no matching consents were found, the consents collection response will have an empty items array.

Parameters

Parameter Description
type
(query)
string (required)
Specify the consent type to rescind.
context
(query)
string(url) (required)
The URI of the consent context.
user
(query)
string(url) (required)
Rescind all matching consents for the user with this user ID.
document
(query)
string(url)
The URI of the target document. This is not required but if passed, the document.uri must match as well as the other required query parameters.

Example responses

200 Response

{
  "_profile": "https://api.apiture.com/schemas/consents/consents/v1.0.0/profile.json",
  "start": 10,
  "limit": 10,
  "count": 67,
  "name": "consents",
  "_links": {
    "self": {
      "href": "/consents/consents?start=10&limit=10"
    },
    "first": {
      "href": "/consents/consents?start=0&limit=10"
    },
    "next": {
      "href": "/consents/consents?start=20&limit=10"
    },
    "collection": {
      "href": "/consents/consents"
    }
  },
  "_embedded": {
    "items": [
      {
        "_id": "0399abed-fd3d-4830-a88b-30f38b8a365c",
        "_profile": "https://api.apiture.com/schemas/consents/consent/v1.0.0/profile.json",
        "_links": {
          "self": {
            "href": "/consents/consents/0399abed-fd3d-4830-a88b-30f38b8a365c"
          }
        }
      },
      {
        "_id": "d62c0701-0d74-4836-83f9-ebf3709442ea",
        "_profile": "https://api.apiture.com/schemas/consents/consent/v1.0.0/profile.json",
        "_links": {
          "self": {
            "href": "/consents/consents/d62c0701-0d74-4836-83f9-ebf3709442ea"
          }
        }
      }
    ]
  }
}

Responses

StatusDescription
200 OK
OK. The operation succeeded. The matching consents are updated and their state changed to rescinded.
Schema: consents
400 Bad Request
Bad Request. One or more query parameters is not well-formed.
Schema: errorResponse
412 Precondition Failed
Precondition Failed. The supplied If-Match header value does not match the most recent ETag response header value. The resource has changed in the interim.
Schema: errorResponse

Response Headers

StatusDescription
200 ETag string
The ETag response header specifies an entity tag which must be provided in an If-Match request header for operations which update the resource.

Consent Type Name

Allowed consent types

getConsentTypeNames

Code samples

# You can also use wget
curl -X GET /consents/consentTypeNames \
  -H 'Accept: application/hal+json' \
  -H 'API-Key: API_KEY' \
  -H 'Authorization: Bearer {access-token}'

GET /consents/consentTypeNames HTTP/1.1

Accept: application/hal+json

var headers = {
  'Accept':'application/hal+json',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: '/consents/consentTypeNames',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/hal+json',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

fetch('/consents/consentTypeNames',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/hal+json',
  'API-Key' => 'API_KEY',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get '/consents/consentTypeNames',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/hal+json',
  'API-Key': 'API_KEY',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('/consents/consentTypeNames', params={

}, headers = headers)

print r.json()

URL obj = new URL("/consents/consentTypeNames");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/hal+json"},
        "API-Key": []string{"API_KEY"},
        "Authorization": []string{"Bearer {access-token}"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "/consents/consentTypeNames", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

Retrieve the set of consent type names

GET /consentTypeNames

Return the set of reserved consent type names. The name property of a consent must be one of these reserved names. This list may be updated by the financial institution via the updateConsentTypeNames operation. The default list includes the following names:

Example responses

200 Response

{
  "_profile": "https://api.apiture.com/schemas/consents/consentTypeNames/v1.0.0/model.json",
  "names": {
    "termsAndConditions": [
      {
        "label": "Term and Conditions",
        "description": "The terms and conditions of use for bank accounts. The user must consent to these terms and conditions in order to open a new account."
      }
    ],
    "privacyPolicy": [
      {
        "label": "Privacy Policy",
        "description": "The financial institution's privacy policy, which covers how the financial institution guards the customer's personal information and how it shares information about customers."
      }
    ],
    "electronicConsent": [
      {
        "label": "Electronic Consent Agreement",
        "description": "Consenting to this agreement means the user agrees to receive electronically certain information such as statements or notices  from the financial institution, and that the user agrees their use of the banking applications means they agree to allow those banking applications to perform banking operations, including transferring money or making payments, on their behalf."
      }
    ]
  }
}

Responses

StatusDescription
200 OK
OK
Schema: consentTypeNames

Response Headers

StatusDescription
200 ETag string
The ETag response header specifies an entity tag which must be provided in an If-Match request header for operations which update the resource.

updateConsentTypeNames

Code samples

# You can also use wget
curl -X PUT /consents/consentTypeNames \
  -H 'Content-Type: application/hal+json' \
  -H 'Accept: application/hal+json' \
  -H 'If-Match: string' \
  -H 'API-Key: API_KEY' \
  -H 'Authorization: Bearer {access-token}'

PUT /consents/consentTypeNames HTTP/1.1

Content-Type: application/hal+json
Accept: application/hal+json
If-Match: string

var headers = {
  'Content-Type':'application/hal+json',
  'Accept':'application/hal+json',
  'If-Match':'string',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: '/consents/consentTypeNames',
  method: 'put',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');
const inputBody = '{
  "_profile": "https://api.apiture.com/schemas/consents/consentTypeNames/v1.0.0/model.json",
  "names": {
    "termsAndConditions": [
      {
        "label": "Term and Conditions",
        "description": "The terms and conditions of use for bank accounts. The user must consent to these terms and conditions in order to open a new account."
      }
    ],
    "privacyPolicy": [
      {
        "label": "Privacy Policy",
        "description": "The financial institution's privacy policy, which covers how the financial institution guards the customer's personal information and how it shares information about customers."
      }
    ],
    "electronicConsent": [
      {
        "label": "Electronic Consent Agreement",
        "description": "Consenting to this agreement means the user agrees to receive electronically certain information such as statements or notices  from the financial institution, and that the user agrees their use of the banking applications means they agree to allow those banking applications to perform banking operations, including transferring money or making payments, on their behalf."
      }
    ]
  }
}';
const headers = {
  'Content-Type':'application/hal+json',
  'Accept':'application/hal+json',
  'If-Match':'string',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

fetch('/consents/consentTypeNames',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/hal+json',
  'Accept' => 'application/hal+json',
  'If-Match' => 'string',
  'API-Key' => 'API_KEY',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.put '/consents/consentTypeNames',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/hal+json',
  'Accept': 'application/hal+json',
  'If-Match': 'string',
  'API-Key': 'API_KEY',
  'Authorization': 'Bearer {access-token}'
}

r = requests.put('/consents/consentTypeNames', params={

}, headers = headers)

print r.json()

URL obj = new URL("/consents/consentTypeNames");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("PUT");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/hal+json"},
        "Accept": []string{"application/hal+json"},
        "If-Match": []string{"string"},
        "API-Key": []string{"API_KEY"},
        "Authorization": []string{"Bearer {access-token}"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("PUT", "/consents/consentTypeNames", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

Replace the set of consent type names

PUT /consentTypeNames

A financial institution can use this operation to register additional types of consent that they may request from their users. The type property of a consent must be one of these reserved names. This operation completely replaces the set of reserved consent type names, so it should include all items from the getConsentTypeNames that are in use. This operation is only available to financial institution administrators.

Body parameter

{
  "_profile": "https://api.apiture.com/schemas/consents/consentTypeNames/v1.0.0/model.json",
  "names": {
    "termsAndConditions": [
      {
        "label": "Term and Conditions",
        "description": "The terms and conditions of use for bank accounts. The user must consent to these terms and conditions in order to open a new account."
      }
    ],
    "privacyPolicy": [
      {
        "label": "Privacy Policy",
        "description": "The financial institution's privacy policy, which covers how the financial institution guards the customer's personal information and how it shares information about customers."
      }
    ],
    "electronicConsent": [
      {
        "label": "Electronic Consent Agreement",
        "description": "Consenting to this agreement means the user agrees to receive electronically certain information such as statements or notices  from the financial institution, and that the user agrees their use of the banking applications means they agree to allow those banking applications to perform banking operations, including transferring money or making payments, on their behalf."
      }
    ]
  }
}

Parameters

Parameter Description
If-Match
(header)
string
The entity tag that was returned in the ETag response. This must match the current entity tag of the resource.
body
(body)
consentTypeNames (required)
The set of consent type names

Example responses

200 Response

{
  "_profile": "https://api.apiture.com/schemas/consents/consentTypeNames/v1.0.0/model.json",
  "names": {
    "termsAndConditions": [
      {
        "label": "Term and Conditions",
        "description": "The terms and conditions of use for bank accounts. The user must consent to these terms and conditions in order to open a new account."
      }
    ],
    "privacyPolicy": [
      {
        "label": "Privacy Policy",
        "description": "The financial institution's privacy policy, which covers how the financial institution guards the customer's personal information and how it shares information about customers."
      }
    ],
    "electronicConsent": [
      {
        "label": "Electronic Consent Agreement",
        "description": "Consenting to this agreement means the user agrees to receive electronically certain information such as statements or notices  from the financial institution, and that the user agrees their use of the banking applications means they agree to allow those banking applications to perform banking operations, including transferring money or making payments, on their behalf."
      }
    ]
  }
}

Responses

StatusDescription
200 OK
OK
Schema: consentTypeNames
400 Bad Request
Bad Request. The request body is badly formed or contains invalid data.
Schema: #/components/responses/400
409 Conflict
Conflict. The request attempts to remove a type that is in use in existing consent resources.
Schema: #/components/responses/409ConsentTypeListConflict

Response Headers

StatusDescription
200 ETag string
The ETag response header specifies an entity tag which must be provided in an If-Match request header for operations which update the resource.

Schemas

consentFields

{
  "document": {
    "uri": "string",
    "contentType": "application/pdf",
    "revisionId": "2019:1.2.0",
    "revisedAt": "2019-10-29T18:22:16Z"
  },
  "type": "string",
  "contextUri": "string",
  "userId": "string"
}

Consent Fields

Common fields of the consent resource used to build other model schemas.

Properties

NameDescription
document document
Properties of the target document.
type string
Describe what kind of consent this is. This value must be one of the type names in the /consentTypeNames resource.
contextUri string(url)
The URI of a resource that establishes the context in which the user's consent is requested for a specific document. For example, for consent of an account's terms and conditions, the context might be the banking product for that account.
userId string
The user ID of the user who is requested to consent to a document. This is the _id of the User resource.

document

{
  "uri": "string",
  "contentType": "application/pdf",
  "revisionId": "2019:1.2.0",
  "revisedAt": "2019-10-29T18:22:16Z"
}

Document

Properties of a target document.

Properties

NameDescription
uri string(url) (required)
The URI of the target document that the user is consenting to. If the document is revised, this consent is marked as stale. (Note: This need not be a document in the Apiture vault.)
contentType any (required)
The media type for the document. For text documents, the content type should include the text encoding; if omitted, the encoding type is assumed to be utf-8.
revisionId string
The revision identifier of the document revision the user consented to. If the content management system in which the document is stored does not define revision identifiers or tags, this may be omitted and will default to the revision time stamp.
revisedAt string(date-time) (required)
The time stamp when the target document was last revised (modified), in RFC 3339 UTC date-time format (YYYY-MM-DDThh:mm:ss.sssZ).

createConsent

{
  "_profile": "https://api.apiture.com/schemas/consents/createConsent/v1.0.0/profile.json",
  "document": {
    "uri": "/vault/files/fd44d565-0086-4caf-8d9f-3b7681809251/content",
    "contentType": "application/pdf",
    "revisionId": "2019:1.02.0",
    "revisedAt": "2019-07-23T08:26:45.375Z"
  },
  "type": "termsAndConditions",
  "userId": "5a5e834c-a7bd-401c",
  "contextUri": "/products/products/34011fe5-192d-4ffb-be32-e7215e56028a"
}

Create Consent

Representation used to create a new consent.

Properties

NameDescription
document document (required)
Properties of the target document.
type string (required)
Describe what kind of consent this is. This value must be one of the type names in the /consentTypeNames resource.
contextUri string(url)
The URI of a resource that establishes the context in which the user's consent is requested for a specific document. For example, for consent of an account's terms and conditions, the context might be the banking product for that account.
userId string (required)
The user ID of the user who is requested to consent to a document. This is the _id of the User resource.
_links object
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
» additionalProperties link
Describes a hypermedia link within a _links object in HAL representations. In Apiture APIs, links are HAL links, but Apiture APIs do not use the name or hreflang properties of HAL. Apiture links may include a method property.
_embedded object
An optional map of nested resources, mapping each nested resource name to a nested resource representation.
_profile string(uri)
The URI of a resource profile which describes the representation.
_error error
An object which describes an error. This value is omitted if the operation succeeded without error.

summaryConsent

{
  "_id": "0399abed-fd3d-4830-a88b-30f38b8a365c",
  "_profile": "https://api.apiture.com/schemas/consents/summaryConsent/v1.0.0/profile.json",
  "document": {
    "uri": "/vault/files/fd44d565-0086-4caf-8d9f-3b7681809251/content",
    "contentType": "application/pdf",
    "revisedAt": "2019-07-23T08:26:45.375Z"
  },
  "type": "termsAndConditions",
  "userId": "5a5e834c-a7bd-401c",
  "state": "pending",
  "contextUri": "/products/products/34011fe5-192d-4ffb-be32-e7215e56028a",
  "_links": {
    "self": {
      "href": "/consents/consents/0399abed-fd3d-4830-a88b-30f38b8a365c"
    }
  }
}

Consent Summary

Summary representation of a consent resource in consents collections. This representation normally does not contain any _embedded objects. If needed, call the GET operation on the item's self link to get _embedded objects.

Properties

NameDescription
document document
Properties of the target document.
type string
Describe what kind of consent this is. This value must be one of the type names in the /consentTypeNames resource.
contextUri string(url)
The URI of a resource that establishes the context in which the user's consent is requested for a specific document. For example, for consent of an account's terms and conditions, the context might be the banking product for that account.
userId string
The user ID of the user who is requested to consent to a document. This is the _id of the User resource.
_links object
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
» additionalProperties link
Describes a hypermedia link within a _links object in HAL representations. In Apiture APIs, links are HAL links, but Apiture APIs do not use the name or hreflang properties of HAL. Apiture links may include a method property.
_embedded object
An optional map of nested resources, mapping each nested resource name to a nested resource representation.
_profile string(uri)
The URI of a resource profile which describes the representation.
_error error
An object which describes an error. This value is omitted if the operation succeeded without error.
_id string
The unique identifier for this consent resource. This is an immutable opaque string.
state consentStates
The state of this consent.
read-only
givenAt string(date-time)
The time stamp when the user last consented to the document, in RFC 3339 UTC date-time format (YYYY-MM-DDThh:mm:ss.sssZ). This property is not set if state is pending.
read-only
requestRevokedAt string(date-time)
The time stamp when the user revoked consent, in RFC 3339 UTC date-time format (YYYY-MM-DDThh:mm:ss.sssZ). A revoked consent reflects a consent request that the user has previously given but has reversed. Revoking a consent sets the state back to pending and clears consentedAt.
read-only
requestRescindedAt string(date-time)
The time stamp when the consent request was rescinded by the requester, in RFC 3339 UTC date-time format (YYYY-MM-DDThh:mm:ss.sssZ). A rescinded consent reflects a consent request that the system or application has issued in the past but no longer requires. For example, if a user is removed as an authorized signer from an account and a consent is pending for that account's terms and conditions, the Accounts service may rescind that consent request. This property is set only if state is rescinded.
read-only

consentStates

"pending"

Consent States

The state of a consent resource.

Type: string
Enumerated values:
pending
given
stale
rescinded
revoked

consent

{
  "_id": "0399abed-fd3d-4830-a88b-30f38b8a365c",
  "_profile": "https://api.apiture.com/schemas/consents/consent/v1.0.0/profile.json",
  "document": {
    "uri": "/vault/files/fd44d565-0086-4caf-8d9f-3b7681809251/content",
    "contentType": "application/pdf",
    "revisionId": "2019:1.02.0",
    "revisedAt": "2019-07-23T08:26:45.375Z"
  },
  "state": "given",
  "givenAt": "2019-07-23T13:27:34.375Z",
  "type": "termsAndConditions",
  "userId": "5a5e834c-a7bd-401c",
  "contextUri": "/products/products/34011fe5-192d-4ffb-be32-e7215e56028a",
  "_links": {
    "self": {
      "href": "/consents/consents/0399abed-fd3d-4830-a88b-30f38b8a365c"
    },
    "apiture:revoke": {
      "href": "/consents/revokedConsents?consent=0399abed-fd3d-4830-a88b-30f38b8a365c"
    },
    "apiture:rescind": {
      "href": "/consents/rescindedConsents?consent=0399abed-fd3d-4830-a88b-30f38b8a365c"
    }
  }
}

Consent

Representation of a consent resource. Users consent or acceptance of a policy or other document.

Properties

NameDescription
document document
Properties of the target document.
type string
Describe what kind of consent this is. This value must be one of the type names in the /consentTypeNames resource.
contextUri string(url)
The URI of a resource that establishes the context in which the user's consent is requested for a specific document. For example, for consent of an account's terms and conditions, the context might be the banking product for that account.
userId string
The user ID of the user who is requested to consent to a document. This is the _id of the User resource.
_links object
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
» additionalProperties link
Describes a hypermedia link within a _links object in HAL representations. In Apiture APIs, links are HAL links, but Apiture APIs do not use the name or hreflang properties of HAL. Apiture links may include a method property.
_embedded object
An optional map of nested resources, mapping each nested resource name to a nested resource representation.
_profile string(uri)
The URI of a resource profile which describes the representation.
_error error
An object which describes an error. This value is omitted if the operation succeeded without error.
_id string
The unique identifier for this consent resource. This is an immutable opaque string.
state consentStates
The state of this consent.
read-only
givenAt string(date-time)
The time stamp when the user last consented to the document, in RFC 3339 UTC date-time format (YYYY-MM-DDThh:mm:ss.sssZ). This property is not set if state is pending.
read-only
requestRevokedAt string(date-time)
The time stamp when the user revoked consent, in RFC 3339 UTC date-time format (YYYY-MM-DDThh:mm:ss.sssZ). A revoked consent reflects a consent request that the user has previously given but has reversed. Revoking a consent sets the state back to pending and clears consentedAt.
read-only
requestRescindedAt string(date-time)
The time stamp when the consent request was rescinded by the requester, in RFC 3339 UTC date-time format (YYYY-MM-DDThh:mm:ss.sssZ). A rescinded consent reflects a consent request that the system or application has issued in the past but no longer requires. For example, if a user is removed as an authorized signer from an account and a consent is pending for that account's terms and conditions, the Accounts service may rescind that consent request. This property is set only if state is rescinded.
read-only

consents

{
  "_profile": "https://api.apiture.com/schemas/consents/consents/v1.0.0/profile.json",
  "start": 10,
  "limit": 10,
  "count": 67,
  "name": "consents",
  "_links": {
    "self": {
      "href": "/consents/consents?start=10&limit=10"
    },
    "first": {
      "href": "/consents/consents?start=0&limit=10"
    },
    "next": {
      "href": "/consents/consents?start=20&limit=10"
    },
    "collection": {
      "href": "/consents/consents"
    }
  },
  "_embedded": {
    "items": [
      {
        "_id": "0399abed-fd3d-4830-a88b-30f38b8a365c",
        "_profile": "https://api.apiture.com/schemas/consents/consent/v1.0.0/profile.json",
        "_links": {
          "self": {
            "href": "/consents/consents/0399abed-fd3d-4830-a88b-30f38b8a365c"
          }
        }
      },
      {
        "_id": "d62c0701-0d74-4836-83f9-ebf3709442ea",
        "_profile": "https://api.apiture.com/schemas/consents/consent/v1.0.0/profile.json",
        "_links": {
          "self": {
            "href": "/consents/consents/d62c0701-0d74-4836-83f9-ebf3709442ea"
          }
        }
      }
    ]
  }
}

Consent Collection

Collection of consents. The items in the collection are ordered in the _embedded.items array; the name is consents. The top-level _links object may contain pagination links (self, next, prev, first, last, collection).

Properties

NameDescription
_links object
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
» additionalProperties link
Describes a hypermedia link within a _links object in HAL representations. In Apiture APIs, links are HAL links, but Apiture APIs do not use the name or hreflang properties of HAL. Apiture links may include a method property.
_embedded object
Embedded objects.
» items [summaryConsent]
An array containing a page of consent items.
_profile string(uri)
The URI of a resource profile which describes the representation.
_error error
An object which describes an error. This value is omitted if the operation succeeded without error.
count integer
The number of items in the collection. This value is optional and my be omitted if the count is not computable efficiently. If a filter is applied to the collection (either implicitly or explicitly), the count, if present, indicates the number of items that satisfy the filter.
start integer
The start index of this page of items.
limit integer
The maximum number of items per page.
name string
The name of the collection.

revisedDocument

{
  "_profile": "https://api.apiture.com/schemas/consents/revisedDocument/v1.0.0/profile.json",
  "uri": "/vault/files/fd44d565-0086-4caf-8d9f-3b7681809251/content",
  "revisionId": "2019:1.2.0",
  "contextUri": "/products/products/34011fe5-192d-4ffb-be32-e7215e56028a",
  "revisedAt": "2019-10-05T10:30:00.000Z",
  "type": "termsAndConditions",
  "newUri": "/vault/files/da66d490-2b72-4809-9b97-9b33039371f8/content"
}

Revised Document

Details about a target document that has been revised.

Properties

NameDescription
uri string(url) (required)
The URI of the target document that the user is consenting to. If the document is revised, this consent is marked as stale. (Note: This need not be a document in the Apiture vault.)
contentType any
The media type for the document. For text documents, the content type should include the text encoding; if omitted, the encoding type is assumed to be utf-8.
revisionId string
The revision identifier of the document revision the user consented to. If the content management system in which the document is stored does not define revision identifiers or tags, this may be omitted and will default to the revision time stamp.
revisedAt string(date-time) (required)
The time stamp when the target document was last revised (modified), in RFC 3339 UTC date-time format (YYYY-MM-DDThh:mm:ss.sssZ).
_links object
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
» additionalProperties link
Describes a hypermedia link within a _links object in HAL representations. In Apiture APIs, links are HAL links, but Apiture APIs do not use the name or hreflang properties of HAL. Apiture links may include a method property.
_embedded object
An optional map of nested resources, mapping each nested resource name to a nested resource representation.
_profile string(uri)
The URI of a resource profile which describes the representation.
_error error
An object which describes an error. This value is omitted if the operation succeeded without error.
newUri string(url)
The URI of the revised target document, if the document has moved. All matching consents will have their document.uri updated to this new document URI.
contextUri string(url)
The URI of a resource that establishes the context in which the user's consent is requested for a specific document. For example, for consent of an account's terms and conditions, the context might be the banking product for that account.
type string (required)
Describe what kind of consent this is. This value must be one of the type names in the /consentTypeNames resource.

consentTypeNames

{
  "_profile": "https://api.apiture.com/schemas/consents/consentTypeNames/v1.0.0/model.json",
  "names": {
    "termsAndConditions": [
      {
        "label": "Term and Conditions",
        "description": "The terms and conditions of use for bank accounts. The user must consent to these terms and conditions in order to open a new account."
      }
    ],
    "privacyPolicy": [
      {
        "label": "Privacy Policy",
        "description": "The financial institution's privacy policy, which covers how the financial institution guards the customer's personal information and how it shares information about customers."
      }
    ],
    "electronicConsent": [
      {
        "label": "Electronic Consent Agreement",
        "description": "Consenting to this agreement means the user agrees to receive electronically certain information such as statements or notices  from the financial institution, and that the user agrees their use of the banking applications means they agree to allow those banking applications to perform banking operations, including transferring money or making payments, on their behalf."
      }
    ]
  }
}

Consent Type Names

A list of allowed consent type names and their labels and descriptions.

Properties

NameDescription
_links object
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
» additionalProperties link
Describes a hypermedia link within a _links object in HAL representations. In Apiture APIs, links are HAL links, but Apiture APIs do not use the name or hreflang properties of HAL. Apiture links may include a method property.
_embedded object
An optional map of nested resources, mapping each nested resource name to a nested resource representation.
_profile string(uri)
The URI of a resource profile which describes the representation.
_error error
An object which describes an error. This value is omitted if the operation succeeded without error.
names localizedLabels
An object which maps consent type names to their labels and descriptions.

localizedLabels

{
  "property1": [
    {
      "label": "Limited Liability Corporation",
      "description": "string",
      "language": "en-us",
      "code": "31"
    }
  ],
  "property2": [
    {
      "label": "Limited Liability Corporation",
      "description": "string",
      "language": "en-us",
      "code": "31"
    }
  ]
}

Localized Labels

An object that maps a name to an array of labels, descriptions and a language (locale) code for the label and description. The first item in the array should be the default label/description; the remaining items must have a language.

Properties

NameDescription
additionalProperties [localizedLabel]
[A localized label and optional description for localizable content defined in this API.]

localizedLabel

{
  "label": "Limited Liability Corporation",
  "description": "string",
  "language": "en-us",
  "code": "31"
}

Localized Label

A localized label and optional description for localizable content defined in this API.

Properties

NameDescription
label string
A localized label or title which may be used to decorate UI controls which present a value.
description string
A more detailed localized description of this label.
language string
The natural language tag to which this localized label is associated, as per RFC 7231. If empty, this item serves as the default label in case no label matches the caller's language.
code string
If the localized value is associated with an external standard, this is a lookup code or key or URI for that value.

root

{
  "id": "apiName",
  "name": "API name",
  "apiVersion": "1.0.0",
  "_profile": "https://api.apiture.com/schemas/common/root/v1.0.0/profile.json",
  "_links": {}
}

API Root

A HAL response, with hypermedia _links for the top-level resources and operations in API.

Properties

NameDescription
_links object
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
» additionalProperties link
Describes a hypermedia link within a _links object in HAL representations. In Apiture APIs, links are HAL links, but Apiture APIs do not use the name or hreflang properties of HAL. Apiture links may include a method property.
_embedded object
An optional map of nested resources, mapping each nested resource name to a nested resource representation.
_profile string(uri)
The URI of a resource profile which describes the representation.
_error error
An object which describes an error. This value is omitted if the operation succeeded without error.
_id string
This API's unique ID.
name string
This API's name.
apiVersion string
This API's version.

errorResponse

{
  "_profile": "https://api.apiture.com/schemas/common/errorResponse/v1.0.0/profile.json",
  "_error": {
    "_id": "2eae46e1-575c-4d69-8a8f-0a7b0115a4b3",
    "message": "The value for deposit must be greater than 0.",
    "statusCode": 422,
    "type": "positiveNumberRequired",
    "attributes": {
      "value": -125.5
    },
    "remediation": "Provide a value which is greater than 0",
    "occurredAt": "2018-01-25T05:50:52.375Z",
    "_links": {
      "describedby": {
        "href": "https://api.apiture.com/errors/positiveNumberRequired"
      }
    },
    "_embedded": {
      "errors": []
    }
  }
}

Error Response

Describes an error response, typically returned on 4xx or 5xx errors from API operations. The _error object contains the error details.

Properties

NameDescription
_links object
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
» additionalProperties link
Describes a hypermedia link within a _links object in HAL representations. In Apiture APIs, links are HAL links, but Apiture APIs do not use the name or hreflang properties of HAL. Apiture links may include a method property.
_embedded object
An optional map of nested resources, mapping each nested resource name to a nested resource representation.
_profile string(uri)
The URI of a resource profile which describes the representation.
_error error
An object which describes an error. This value is omitted if the operation succeeded without error.

{
  "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
  "title": "Applicant"
}

Link

Describes a hypermedia link within a _links object in HAL representations. In Apiture APIs, links are HAL links, but Apiture APIs do not use the name or hreflang properties of HAL. Apiture links may include a method property.

Properties

NameDescription
href string(uri) (required)
The URI or URI template for the resource/operation this link refers to.
type string
The media type for the resource.
templated boolean
If true, the link's href is a URI template.
title string
An optional human-readable localized title for the link.
deprecation string(uri)
If present, the containing link is deprecated and the value is a URI which provides human-readable text information about the deprecation.
profile string(uri)
The URI of a profile document, a JSON document which describes the target resource/operation.

error

{
  "_id": "2eae46e1-575c-4d69-8a8f-0a7b0115a4b3",
  "message": "The value for deposit must be greater than 0.",
  "statusCode": 422,
  "type": "positiveNumberRequired",
  "attributes": {
    "value": -125.5
  },
  "remediation": "Provide a value which is greater than 0",
  "occurredAt": "2018-01-25T05:50:52.375Z",
  "_links": {
    "describedby": {
      "href": "https://developer.apiture.com/errors/positiveNumberRequired"
    }
  },
  "_embedded": {
    "errors": []
  }
}

Error

Describes an error in an API request or in a service called via the API.

Properties

NameDescription
message string (required)
A localized message string describing the error condition.
_id string
A unique identifier for this error instance. This may be used as a correlation ID with the root cause error (i.e. this ID may be logged at the source of the error). This is is an opaque string.
statusCode integer
The HTTP status code associate with this error.
minimum: 100
maximum: 599
type string
An error identifier which indicates the category of error and associate it with API support documentation or which the UI tier can use to render an appropriate message or hint. This provides a finer level of granularity than the statusCode. For example, instead of just 400 Bad Request, the type may be much more specific. such as integerValueNotInAllowedRange or numericValueExceedsMaximum or stringValueNotInAllowedSet.
occurredAt string(date-time)
An RFC 3339 UTC time stamp indicating when the error occurred.
attributes attributes
Informative values or constraints which describe the error. For example, for a value out of range error, the attributes may specify the minimum and maximum values. This allows clients to present error messages as they see fit (the API does not assume the client/presentation tier). The set of attributes varies by error type.
remediation string
An optional localized string which provides hints for how the user or client can resolve the error.
errors [error]
An optional array of nested error objects. This property is not always present.
_links links
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
_embedded object
Embedded objects. An error object may contain nested errors. For example, an API which validates its request body may find multiple errors in the request, which are returned with an error response with nested errors. These are held in an items array of errorResponse objects. _embedded or _embedded.items may not exist if the error does not have nested errors. This property is deprecated; use see error.errors instead.
» items [errorResponse]
An array of error objects.

attributes

{}

Attributes

An optional map of name/value pairs which contains additional dynamic data about the resource.

Properties

{
  "property1": {
    "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
    "title": "Applicant"
  },
  "property2": {
    "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
    "title": "Applicant"
  }
}

Links

An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.

Properties

NameDescription
additionalProperties link
Describes a hypermedia link within a _links object in HAL representations. In Apiture APIs, links are HAL links, but Apiture APIs do not use the name or hreflang properties of HAL. Apiture links may include a method property.