Piano middleware application management API

This is the sandbox API for ABS version 1.1.12

The API URL is https://ns-sandbox-abs.piano.io/

API parameters:

  • Authorization - type: string - mandatory for all requests. Should be in the request headers.
  • All endpoints should use POST method
  • Parameters should be provided within a JSON body.

    • Create new entitlement

    Endpoint: /access/create

    List of parameters:

    Parameter Example Comment
    aegisUserId 10015658 Optional - if empty, a new user will be created.
    firstName John Optional if Company name is provided.
    lastName Smith Optional if Company name is provided.
    email john.smith@aol.com Mandatory parameter. Please do not forget to encode special symbols like '+'.
    absSubscriberNumber 1234 Mandatory parameter.
    absSubscriptionNumber 5678 Mandatory parameter.
    dpaDirectMail y Optional. Corresponds to 'dpa_ns_direct_mail' Piano custom field.
    dpaEmail y Optional. Corresponds to 'dpa_ns_email' Piano custom field.
    dpaPhone n Optional. Corresponds to 'dpa_ns_telephone' Piano custom field.
    dpaMobile y Optional. Corresponds to 'dpa_ns_sms' Piano custom field.
    addressId UATBB2UX9W53 Optional - if empty, a new address will be created.Should not be provided if aegisUserId is empty.
    companyName Smith and sons, inc. Optional if both first_name and last_name are provided, otherwise mandatory.
    address1 Northern road, 6 Mandatory parameter.
    address2 Central square, 12 Optional.
    addressCity Chester city Mandatory parameter.
    addressRegionCode BL Mandatory if country has regions. Not applicable for UK.
    addressCountryCode SK Mandatory parameter. List of country codes and region codes should be taken from https://api-eu.piano.io/api/v3/anon/country/list/country
    postalCode 123456 Mandatory parameter.
    phone +441324354657 Optional.
    accessResourceId XAUT Mandatory parameter.
    accessEndDate 2023-11-25 Mandatory parameter. Should be more than yesterday, ISO date without time.

    Response codes:

    Code Reason
    200 Successful entitlement creation. Response will contain 'aegisUserId', 'accessId' and 'addressId'.
    201 A user already had relevant access. Data will be updated and response will contain ids.
    202 Partial success - access was given but correct date was not set.
    203 Request data validation issue.
    400 Bad request. Please check query parameters.
    401 Incorrect authorisation, please check your API key.
    500 Internal server error

    Extend an entitlement

    Endpoint: /access/extend

    List of query parameters:

    Parameter Example Comment
    aegisUserId 10015658 Mandatory parameter.
    accessId eYJjPtJHfFdm Mandatory parameter.
    accessResourceId XAUT Mandatory parameter.
    accessEndDate 2023-11-25 Mandatory parameter. Should be more than yesterday, ISO date without time.

    Response codes:

    Code Reason
    200 Successful entitlement update. Response will contain 'aegisUserId' and 'accessId'.
    203 Request data validation issue.
    400 Bad request. Please check query parameters.
    401 Incorrect authorisation, please check your API key.
    500 Internal server error

    Cancel an entitlement

    Endpoint: /access/revoke

    List of query parameters:

    Parameter Example Comment
    aegisUserId 10015658 Mandatory parameter.
    accessId eYJjPtJHfFdm Mandatory parameter.

    Response codes:

    Code Reason
    200 Successful access revokation.
    203 Request data validation issue.
    400 Bad request. Please check query parameters.
    401 Incorrect authorisation, please check your API key.
    500 Internal server error

    Update a user

    Endpoint: /user/update

    List of query parameters:

    Parameter Example Comment
    aegisUserId 10015658 Mandatory parameter.
    firstName John Mandatory parameter.
    lastName Smith Mandatory parameter.
    email john.smith@aol.com Mandatory parameter.
    absSubscriberNumber 1234 Mandatory parameter.
    absSubscriptionNumber 5678 Mandatory parameter.
    dpaDirectMail y Optional. Corresponds to 'dpa_ns_direct_mail' Piano custom field.
    dpaEmail y Optional. Corresponds to 'dpa_ns_email' Piano custom field.
    dpaPhone n Optional. Corresponds to 'dpa_ns_telephone' Piano custom field.
    dpaMobile y Optional. Corresponds to 'dpa_ns_sms' Piano custom field.

    Response codes:

    Code Reason
    200 Successful user update. Response will contain 'aegisUserId'.
    203 Request data validation issue.
    400 Bad request. Please check query parameters.
    401 Incorrect authorisation, please check your API key.
    500 Internal server error