Introduction

The SERMO Balance and Payments system provides a way to manage honoraria paid out to survey participants. Honoraria and other payments are credited to a member's balance account. Withdrawals may then be made from the account up to the full amount held in the balance. SERMO processes the withdrawal requests and provides payment to the individual.

The SERMO Balance accounts allow individual survey panelists and SERMO members to be credited with funds for honoraria, special gestures, or other payments. The funds are held by SERMO until such time as the account holder makes a withdrawal request.

Note

Honoraria and incentive funds are managed in accordance to the SERMO Terms of Use. Please see the section "Honoraria and Incentives Balances" for further details.

Under Development

This API is under development and not yet final.

General Information

Authentication

All API calls will send the provided credentials using HTTP Basic authentication as described in RFC2617. Credentials will be provided by SERMO.

Description of Usual Server Responses

  • 200 OK - the request was successful (some API calls may return 201 instead).
  • 400 Bad Request - The request could not be understood or was missing required parameters.
  • 401 Unauthorized - "Authentication failed" or "You do not have permissions for requested operation".
  • 403 Forbidden - Access denied.
  • 404 Not Found - The requested resource is not available or user not found.
  • 405 Method Not Allowed - The requested method is not supported for resource.
  • 422 Unprocessable Entity - The request entity has one or more properties missing or invalid.
  • 503 Service Unavailable - The service is temporary unavailable. Try again later.

Standard formats

  • The currency for each amount is three letter ISO-4217 code. See more about ISO-4217 format. Examples:
    • USD (United States dollar)
    • CHF (Swiss franc)
  • All datetimes are in compliance with ISO-8601 format
    • Example of UTC (Coordinated Universal Time): 2017-02-02T13:44:05+00:00
    • Example of EST (Eastern Standard Time): 2017-02-02T13:44:05-05:00
  • Region code are in compliance with ISO-3166-2 format. For example:
    • US-AL (Alabama)
    • US-MA (Massachusetts)
  • Country codes are in compliance with ISO 3166-1 alpha-2 format. For example:
    • US (United States of America)
    • MX (Mexico)
    • FR (France)

Identifying User Accounts

Each individual has an associated Balance Account. This is where we track credits for survey completion honoraria, and credits for honoraria withdrawals. A given balance account may be looked up through various identifiers that each refer to the same person. These identifiers include:

  • SERMO user ID
  • NPI (for US members)
  • GMC (for UK members)
  • AMA ME Number (for US members)
  • Partner IDs stored in SERMO's systems

The URLs referencing a balance account are thus constructed using two different components: a key stating which identifier is being used, and the identifier value itself.

For example, a URL referencing a balance account summary by NPI would look like:

https://host/balance/npi/1234567890/summary

Another referencing the account transactions by partner ID would look like:

https://host/balance/partner_id/THX1138/transactions

Each URL template described below thus has two parameters: a {key} and an {id} value that is part of the URL path. The following are supported values for the {key}:

  • user_id - for the SERMO user ID
  • npi - for the US NPI
  • me - for the US AMA ME Number

Account Information

The Balance account will reflect a sequence of transactions as applied to the account. These may include incentive payments and withdrawals, but may further reflect other credits or debits as needed to correct any issues with the account. Each transaction is thus designated with an appropriate type to properly determine what it is.

API endpoints are provided for obtaining information about these accounts in a flexible manner. Endpoints are accessed over HTTP 1.1, and data is returned with a content type of "application/json".

The summary for the account provides basic information about the account. This is suitable for displaying a summary box or otherwise determining the current account balance.

The transactions for the account provide details about each debit and credit to the account. Each record will include information.

Account Summary

The Account Summary resource provides a high level view of an individual balance account. A person's account is pulled up by a unique identifier for that person. We support a variety of unique identifiers and may add more over time:

GET /balance/{key}/{id}/summary

  • Request query parameters:

  • Response:

    • available_funds - The amount of money in the given currency available for withdrawal.

    • currency - The three-letter ISO code for the currency in which the balance account is managed.

    • preferred_status - Indication whether the individual is given preferred treatment in survey invitations per the SERMO Terms of Use.

  • Example response

    {
    "available_funds": 3823.51,
    "currency": "USD",
    "preferred_status": true
}

Account Transactions

To get all transactions of individual balance account following resource should be used:

GET /balance/{key}/{id}/transactions

Retrieves all related transactions for specified user.

Note

Both withdrawal and deposit transactions has survey_id field, but only deposit will have value and in case of withdrawal it will be null.

  • Request query parameters:

  • Response example:

    • id - Unique ID for transaction

    • amount - decimal amount of withdrawal

    • currency - the three-letter ISO code for the currency

    • type - transaction type. For supported types see in Withdrawal Types section

    • type_description - description of transaction type

    • status - current status of transaction

    • current_balance - current balance. Note: field shows balance up to current transaction inclusively not the total available funds

    • created_date - date and time when transaction was created

    • properties - key:value pairs holding additional transaction's information like with what vendor is transaction associated

      [
    {
        "id": "31b7b165-f715-4945-9d1a-0b1f6e31b662",
        "amount": 150.00,
        "currency": "USD",
        "type": "SRVC1M",
        "type_description": "Survey Complete",
        "status": "Completed",
        "survey_id": "123456",
        "current_balance": 3550.00,
        "created_date": "2017-02-02T13:44:05+00:00",
        "properties": {
            "Vendor": "vendor_name"
        }
    },
    {
        "id": "40fe45ae-95c6-41ed-ad48-ecdcb37c5fd2",
        "amount": -50.00,
        "currency": "USD",
        "type": "AMZNCN",
        "type_description": "Amazon.cn",
        "status": "Completed",
        "survey_id": null,
        "current_balance": 3600.00,
        "created_date": "2017-02-02T13:50:05+00:00",
        "properties": {}
    }
]

  • Response example (404 Not Found)

    • message - message describing server response
      {
    "message": "Individual balance account wasn't found"
}

Transactions

To get single transaction you can use following endpoint:

GET /balance/transactions/{id}

Gets all data asociated with specified transaction.

  • Request query parameters:

    • id Unique transaction GUID generated by SERMO system. Example 907ec5c9-9e59-4fe8-b909-1609ce39ccfd

  • Response example

    • id - Unique ID for transaction

    • amount - decimal amount of transaction

    • currency - amount currency. See more in Standard formats section

    • type - withdrawal transaction type. For supported types see in Withdrawal Types section

    • type_description - description of transaction type

    • status - current status of transaction. Available status values:

      • Processing - Transaction is being processed
      • Completed - Processing was completed
      • Cancelled - Transaction has been cancelled
      • Reversed - Transaction has been reversed
      • OnHold - Transaction processing was put on hold

    • survey_id - unique id referencing project in SERMO system

    • created_date - date and time when transaction was created

    • properties - key:value pairs holding additional transaction's information like with what vendor is transaction associated

      {
    "id": "31b7b165-f715-4945-9d1a-0b1f6e31b662",
    "amount": 150.00,
    "currency": "USD",
    "type": "SRVC1M",
    "type_description": "Survey Complete",
    "status": "Completed",
    "survey_id": "123456",
    "created_date": "2017-02-02T13:44:05+00:00",
    "properties": {
        "Vendor": "vendor_name"
    }
}

  • Response example (404 Not Found)

    • message - message describing error response
      {
    "message": "Transaction with provided id wasn't found"
}

Withdrawal Types

To get all available withdrawal types for an individual account following request should be used:

GET /balance/{key}/{id}/withdrawal_types

  • Request query parameters

  • Response example (200 OK)

    • type - withdrawal type.

    • description - description of withdrawal transaction type.

    • fee - amount of money (in given currency) to be surcharged for witdhrawal.

    • minimum_balance_required - minimum balance (in given currency) required for withdrawal.

    • required_fields - mandatory individual personal data fields to process withdrawal. Each data field has constraints which are listed below.

    • optional_fields - optional individual personal data fields to process withdrawal. Each data field has constraints which are listed below.

      [
    {
        "type": "AMZNUS",
        "description": "Amazon.com",
        "fee": null,
        "minimum_balance_required": null,
        "required_fields": ["first_name", "last_name", "email"],
        "optional_fields": []
    },
    {
        "type": "CHECKS",
        "Description": "Check (HSBC)",
        "fee": {
            "amount": 5,
            "currency": "USD"
        },
        "minimum_balance_required": {
            "amount": 10,
            "currency": "USD"
        },
        "required_fields": ["first_name", "last_name", "address_line1", "city", "postal_code", "country"],
        "optional_fields": ["address_line2", "address_line3"]
    },
    {
        "type": "MASTERCARD",
        "description": "MasterCard",
        "fee": null,
        "minimum_balance_required": null,
        "required_fields": ["first_name", "last_name", "email", "address", "city", "region", "postal_code", "country", "phone_number"],
        "optional_fields": ["address_line2", "address_line3"]
    },
    {
        "type": "CHRTY",
        "description": "Doctors Without Borders (Charity)",
        "fee": null,
        "minimum_balance_required": null,
        "required_fields": ["first_name", "last_name", "email"],
        "optional_fields": []
    }
]

  • Response example (404 Not Found)

    • message - message describing error response
      {
    "message": "Individual balance account wasn't found"
}

Personal data fields has constraints which will be validated before creating withdrawal. A table below are listing all fields with constraints:

Required Field Type Constraints
first_name string First given name
last_name string Surname or family name. Please omit any degrees or honorifics
email string Email address. Make sure this is a valid, deliverable email, or else the member may not receive important status updates regarding the withdrawal
address_line1 string Street address. Include only street, building and, if applicable, apartment number. For example: 216 6 Jacobs Street
address_line2 string Apartment number or floor number. Optional
address_line3 string Neighbourhood or district within a town or city. Optional
city string Name of the city
region string Region code with format defined by ISO-3166-2. For possible values see Regions section.
postal_code string Local postal code
country string Country code. For example: US (United States of America). For possible values see Countries section.
phone_number string The member's international phone number. Number can have whitespace prefix plus and hyphen symbols

To see more about standard formats check Standard formats section.

Create Withdrawal

In order to withdraw funds, a withdrawal transaction is created. Withdrawals may be done through different means, and SERMO regularly updates its available withdrawal options. As such, the withdrawal process is highly dynamic. A successful withdrawal request will result in a withdrawal transaction in the list of available transactions, and a corresponding debit to the total amount available in the Balance account. SERMO will then process the withdrawal and deliver funds through the selected mechanism.

Warning

Available withdrawal types may be different for each individual, therefore you need to check (see Withdrawal Types section) for available withdrawal types before presenting options to individual.

POST /balance/{key}/{id}/withdrawals

For each withdrawal depending on withdrawal type there are required individual personal data to complete payment. See more in Withdrawal Types section. To minimize unsuccessfully processed withdrawals and to keep member's data up to date each time it requires to provide personal details.

  • Request query parameters:

  • Request example

    {
    "type": "AMZNUS",
    "amount": 150.00,
    "member_details": {
        "first_name": "John",
        "last_name": "Smith",
        "email": "j.smith@domain.com"
    }
}

  • Request body fields

    • type [required] - type of withdrawal. For list of available withdrawal types see Withdrawal Types section

    • amount [required] - decimal amount to be debited from individual balance account

    • member_details [required] - individual personal data required to complete different payment options. For list of required fields see Withdrawal Types section

  • Response example (201 Success)

    • transaction_id - unique withdrawal transaction id generated by SERMO system

    • uri - created entity uri

      {
    "transaction_id": "f826edd8-6875-493a-9015-32d68a9ffdd5",
    "uri": "/balance/transactions/f826edd8-6875-493a-9015-32d68a9ffdd5"
}

All possible 4xx series response examples contains single field "message".

  • Response example (400 BadRequest)

    This response may appear if API does not succeed serializing request body or body is missing required fields

        {            
        "message": "Invalid request body"
    }

  • Response example (404 Not Found)

    This response may appear if API does not succeed in retrieving account data by any means.

        {
        "message": "Individual balance account wasn't found"
    }

  • Response example (403 Forbidden)

    This response will appear if requested withdrawal type is restricted for individual.

        {            
        "message": "Invalid withdrawal type: EXAMPLE_TYPE"
    }

  • Response example (422 Unprocessable Entity)

    This response will appear if member_details object has missing required member data fields

        {
        "message": "Required fields are missing or invalid"
    }

Countries

Provides a list of countries that are available for user. It's meant to be used to populate country Required Field used in Create Withdrawal endpoint.

GET /balance/countries

  • Response example (200 Success)

    • alpha_2_code - country alpha-2 code

    • short_name - country short name

      [
    {
        "alpha_2_code": "AD",
        "short_name": "Andorra"
    },
    {
        "alpha_2_code": "AF",
        "short_name": "Afghanistan"
    },
    {
        "alpha_2_code": "AG",
        "short_name": "Antigua and Barbuda"
    },
    ...
]

Regions

Provides a list of regions of specific country. It's meant to be used to populate region Required Field used in Create Withdrawal endpoint.

GET /balance/countries/{countryCode}/regions

  • Request query parameters:

    • countryCode - country alpha-2 code

  • Response example (200 Success)

    • region_code - region code in format defined by ISO-3166-2

    • name - region name

    • alpha_2_code - alpha-2 code of the country that region belongs to

    • postal_abbreviation - region postal abbreviation

      [
    {
        "region_code": "US-AL",
        "name": "Alabama",
        "alpha_2_code": "US",
        "postal_abbreviation": "AL"
    },
    {
        "region_code": "US-AK",
        "name": "Alaska",
        "alpha_2_code": "US",
        "postal_abbreviation": "AK"
    },
    ...
]