SERMO Partner Market Research API

This interface provides a well-defined mechanism for automated execution of SERMO market research projects using partner systems and audiences. The API provides for various resources to model market research projects, survey quotas, and targeting lists for the quotas.

Under Development

Please note that this API definition is still being finalized. It should be considered complete once this note is removed.

Interaction Model

The basic interaction between systems will have SERMO's market research systems pushing updates to the partner's systems as events occur. This prevents the need for polling and allows for near real-time updates as events occur.

Partners will implement the endpoints for the API described herein. SERMO will configure its market research systems to push updates via this API as events occur in its market research systems. New projects will be created and updated, quotas will open and close, with changes being reflected by corresponding PUT calls to the various API endpoints.

The general lifecycle will be:

  1. A new project is created by a PUT to /projects/{project_id}.
  2. Quotas are defined for the project by various PUTs to /projects/{project_id}/quotas/{quota_id} and /projects/{project_id}/quotas/{quota_id}/members.
  3. As the project execute, various PUT calls are made to update quota state.
  4. Once the project completes, PUT calls are made to close all the quotas and mark the project as closed.

Each PUT call will include a full representation of the resource, so no support for partial updates will be needed.

Each resource has a corresponding GET call. Even though the system interaction is a push model, we need a mechanism for troubleshooting. Each GET request must thus reflect the information that the partner captured during the last PUT request to create or update the resource.

Data Types and Formats

All resource representations are to be transferred using JSON as the format. All communications will take place over TLS protected connections (i.e. HTTPS URLs).

There are a few details to note througout:

  • Unless otherwise specified, all timestamps are to be rendered in ISO 8601 format in UTC.

  • IDs used to uniquely identify various resources may appear to be just positive integers, but may be UUIDs or other identifiers. Treat these as opaque strings.

  • Honoraria values may include a fractional component, but will nearly always be a whole integer value in USD. You should use an appropriate monetary data type in your implementation to model these.

Versioning

The base URL for the API endpoint should include a version identifier. This will allow us to make incompatible changes to the API over time if needed, while still preserving the older behavior.

As an example, a request for a particular project could have a URL of the form:

https://mrapi.partner.com/v1/projects/12345

If, over time, we need to make a backwards incompatible change to how the data is represented, we could update the version component to support the new functionality without breaking existing calls.

https://mrapi.partner.com/v2/projects/12345AB-776

Having the versioning in the URL from the start will give us a tool to more easily manage API evolution.

Authentication

All requests will be authenticated using HTTP Basic. The Authorization header will be sent with an agreed upon username and password value. Any API call which does not contain the correct Authorization header must refuse the call and return an HTTP 401 response code.

Group Projects

Project resources allow for the creation of market research projects, distributing invitations to those projects through various means, and ultimately fulfilling the project by having respondents take the provided survey.

Project [/v1/projects/{project_id}]

A project represents the highest abstraction level on which we will execute.

  • Parameters

  • project_id (string, required) - ID of the project to retrieve.

  • Attributes (object)

    • project_id: 12345 (string, required) - The unique ID for the project in SERMO's systems.

    • name: Study of analgesic effects of Aspirin (string, required) - Non-localized name of the project, generally US English. This is the name to be presented to the potential survey participants.

    • custom_text: Special instructions. (string) - Extra descriptive text, including special instructions, to be presented to the survey participant. This additional text will not be provided with every survey.

    • duration: 70 (number, required) - Approximate duration of the survey in minutes.

    • status (enum[string], required)

      • onhold - The project has been pulled out of field to address a problem. No invitations should be sent for any quota. Respondents who follow any existing invitations already in flight will receive a message that the survey is not currently available.

      • active - The project is active and invitations may be sent to recruit participants.

      • closed - The project has terminated and all quotas are closed.

    • project_type (enum[string], required)

      • custom - Custom market research project where quotas will be open for days or longer.

      • real-time - RealTime™ project where the quota may only remain open for hours.

    • created_at: 2016-10-11T14:53:03Z (string, required) - The time the project was created rendered in ISO 8601 format.

    • updated_at: 2016-10-11T14:53:03Z (string, required) - The last time the project was updated in the system in ISO 8601 format.

GET

Retrieval of the project, although not common, will allow verification that all the information is up to date. SERMO may follow up with a PUT request if something needs to be updated to reflect the live market research system.

  • Request

    • Headers
      Authorization: Basic ABCDEF

  • Response 200 (application/json)

    • Attributes (Project)

PUT

Create or update the existing project with the provided information. The project cannot be executed, of course, until the quota information is likewise provided.

  • Request (application/json)

    • Headers

      Authorization: Basic ABCDEF

    • Attributes (Project)

  • Response 200 (application/json)

Quota [/v1/projects/{project_id}/quotas/{quota_id}]

A quota is the basic unit for managing invitations and controlling participation in the survey. This wraps up the basic criteria for whom we wish to invite into the survey.

Each quota is managed independently. They are generally mutually exclusive, and can close at different times. When a quota is closed, all respondents for that quota who attempt to start the survey will be terminated with a Quota Full status.

Quotas will automatically close once enough respondents complete the survey for that quota. Quotas can also be manually closed by the project manager. On occasion, a quota may be reopened in order to obtain more responses.

Quotas will normally be open when the project starts, and remain open until they are fulfilled. Quotas will frequently be updated, and may be closed and reopened. New quotas may be added mid-project as well. This happens in consultation with the market research client as criteria change or adjustments need to be made due to the current number of completed surveys for a quota.

  • Parameters

    • project_id (string) - ID of the project to which the quota belongs

    • quota_id (string) - Quota identifier

  • Attributes

    • quota_id: 123456 (string, required) - Quota identifier

    • project_id: 12345 (string, required) - The unique ID for the project in SERMO's systems.

    • status (enum[string], required)

      • open - New respondents for this quota may enter the survey.

      • closed - No new respondents will be allowed into the survey for this quota.

    • limit: 100 (number, required) - The number of respondents needed to fulfill the quota. Once this number of survey completions have been collected, the quota will automatically close and any future respondents will be notified the quota is full.

    • duration: 60 (number, optional) - Approximate duration of the survey for quota respondents in minutes (if different than project).

    • incidence_rate: 0.13 (number, required) - The expected fraction of participants who will match the quota and pass the screener questions. This will be a value between 0 and 1.

    • type (enum[string])

      • specialty - The quota is defined by the specialties listed in matching_specialties.

      • list_match - The quota is defined by a specific list of individuals requested by the client.

      • other - The quota is defined by selection criteria beyond the specialties listed in matching_specialties.

    • matching_specialties: specialty1, specialty2 (array[string], optional) - The list of specialties defining the members of the quota. Depending on the type of the quota, this may be empty or omitted.

    • matching_regions: TX, MA, PR (array[string], optional) - The list of US states or territories in which the targeted people practice. Only two-letter US Postal Service bbreviations will be provided.

    • cost_per_complete: 40 (number, optional) - Cost to the client per complete in this quota, in USD.

    • cost_per_incentive: 25 (number, optional) - Incentive cost to the client per complete in this quota, in USD.

    • honoraria: 20 (number, optional) - The honoraria offered for successful completion of the survey (for specialty quotas), in USD.

    • url: https://us.onesurvey.com/12345-NPI<npi>-DD (string, optional) - The URL template to which respondent should be sent. Insert the member's NPI in place of the <npi> in the template. The provided URL may encode a variety of information, including data for which quota this member should satisfy (for specialty quotas). Do not modify any other part of it.

    • closes_at: 2016-10-21T14:53:03Z (string, required) - The deadline for this quota. It may be different from that of other quotas. The quota may not automatically close once this deadline is reached, but likely will be closed soon. Use this deadline in any invitation for this quota.

    • created_at: 2016-10-11T14:53:03Z (string, required) - The time the quota was created rendered in ISO 8601 format.

    • updated_at: 2016-10-11T14:53:03Z (string, required) - The last time the quota was updated in the system in ISO 8601 format.

GET

  • Request

    • Headers
      Authorization: Basic ABCDEF

  • Response 200 (application/json)

    • Attributes (Quota)

PUT

  • Request (application/json)

    • Headers

      Authorization: Basic ABCDEF

    • Attributes (Quota)

  • Response 200

Quota Members [/v1/projects/{project_id}/quotas/{quota_id}/members]

A quota will be defined as a list of specific NPI numbers to target. Selection based on specialty and various other criteria will be done within SERMO's market research systems and turned into a list of people to target.

Any quota will likely be updated many times as the project progresses. Market research clients may choose to adjust the selection criteria for a quota which will impact the list of members in that quota. As the list changes, new PUT requests will be sent to update the targeting list in the partner's systems.

  • Parameters

    • project_id (string) - ID of the project to which the quota belongs

    • quota_id (string) - Quota identifier

  • Attributes (array)

    • (object)

      • npi: 1111111111 (string, required) - The NPI number of the person to target.

      • honoraria: 20 (number, required) - The honoraria offered for successful completion of the survey, in USD.

      • url: https://us.onesurvey.com/12345-NPI1234567890-DD (string, required) - The URL to which this participant should be sent. The provided URL may encode a variety of information, including data for which quota this member should satisfy.

GET

Retrieve the full list of quota members.

  • Request

    • Headers
      Authorization: Basic ABCDEF

  • Response 200 (application/json)

    • Attributes (Quota Members)

PUT

Create or update the full list of quota members.

  • Request (application/json)

    • Headers

      Authorization: Basic ABCDEF

    • Attributes (Quota Members)

  • Response 200

POST

Append the provided members to the full list of quota members. Multiple POST calls can be used to transfer the entire member list in smaller chunks when setting up the quota.

  • Request (application/json)

    • Headers

      Authorization: Basic ABCDEF

    • Attributes (Quota Members)

  • Response 200

Quota Member [/v1/projects/{project_id}/quota/{quota_id}/members/{npi}]

  • Parameters

    • project_id (string) - ID of the project to which the quota belongs

    • quota_id (string) - Quota identifier

    • npi (string) - The NPI number of the person to target

  • Attributes (object)

    • npi: 1111111111 (string, required) - The NPI number of the person to target.

    • honoraria: 20 (number, required) - The honoraria offered for successful completion of the survey, in USD.

    • url: https://us.onesurvey.com/12345-NPI1234567890-DD (string, required) - The URL to which this participant should be sent. The provided URL may encode a variety of information, including data for which quota this member should satisfy.

GET

Retrieve the information for the given quota member.

  • Request

    • Headers
      Authorization: Basic ABCDEF

  • Response 200 (application/json)

    • Attributes (Quota Member)

PUT

Update the information for the given quota member.

  • Request (application/json)

    • Headers

      Authorization: Basic ABCDEF

    • Attributes (Quota Member)

  • Response 200

DELETE

Remove the given member from the quota.

  • Request

    • Headers
      Authorization: Basic ABCDEF

  • Response 200

Quota List [/v1/projects/{project_id}/quotas]

Since a project consists of one or more quotas, we want a way to verify that all the needed quotas are currently part of the system.

  • Parameters

    • project_id (string) - ID of the project to which the quotas belong.

GET

  • Request

    • Headers
      Authorization: Basic ABCDEF

  • Response 200 (application/json)

    • Attributes (array[Quota])

Survey Event [/v1/projects/{project_id}/events]

As respondents participate in surveys, partners need to remain updated on their status. Has anyone started the survey? Has anyone completed? SERMO will publish events to partners for each participant so that partners know when to stop presenting that person with a given survey invitation.

  • Parameters

    • project_id (string) - ID of the project for which the event occurred.

  • Attributes (object)

    • npi: 1111111111 (string, required) - NPI number of the participant in the survey.

    • quota_id: 12345 (string, optional/required) - ID of the quota to which this member responded. Since quotas may be not be set until after a survey start, this field is optional when the state is start. It will be provided for all other states.

    • project_id: 12345 (string, required) - ID of the project to which the quota applies.

    • state (enum[string], required)

      • start - The participant started the survey.

      • screenout - The participant was screened out of the survey. Do not present this participant with any more invitations to this survey.

      • quotafull - The participant attempted to start this survey, but the quota had already filled. Do not present this participant with any more invitations to this survey.

      • complete - The participant has successfully completed this survey and will be paid the promised honoraria. Do not present this participant with any more invitations to this survey.

    • event_at: 2016-10-11T23:13:45Z (string, required) - Time at which this event occurred in ISO 8601 format.

POST

  • Request (application/json)

    • Headers

      Authorization: Basic ABCDEF

    • Attributes (Survey Event)

  • Response 200