Related pages

Introduction

The MVault API is a programming interface designed to integrate your app with Passport. This document is intended for developers who want to write applications that interact with Passport. It explains basic concepts of Passport and the API.

Currently, the only resource exposed to the API is Membership.  A membership resource represents a station acknowledgement for a donation made by an individual. The acknowledgement becomes persisted data in the MVault system. The membership can later be connected to a PBS account through a process called membership activation, which results in additional content or longer access periods granted to the account.

Try out the RAML API Console here.

Authentication

In order to access exposed resources, an API consumer needs to be assigned to a Group that is assigned to a specific Station. The protocol for authentication is Basic Auth as defined by the Internet Engineering Task Force, in the Request for Comments number 2617 (http://www.rfc-editor.org/rfc/rfc2617.txt). In order to use this API, Basic Auth protocol must be used.

What is an API Consumer?

An API Consumer is defined by a key (example: john) and a secret (example: mypassword). The key and secret are similar to a username and password and both must be provided to users of the API.

For all supported HTTP request methods see the individual page for each resource. All requests must contain the header Authorization, which contains the name of the authentication method (Basic), followed by a base64 encoded string of type key:secret.

Example

For key = 'john' and secret = 'password' - Authorization: Basic = am9objpteXBhc3N3b3Jk

To obtain am9objpteXBhc3N3b3Jk, we took the string john:mypassword and used a tool like http://www.base64encode.org/ to encode it.

How do I obtain authentication credentials?

To obtain authentication credentials please submit a support ticket. 

Date and Time

All date time fields are represented in UTC format. Please be sure to use UTC format, otherwise odd calculus may occur!

Activation

Activation is the process of making an MVault Membership live and usable so that a Passport user may view Passport content. This is in contrast to 'deactivation' which is to 'turn off' a user's ability to use her membership for Passport content.

In order to Activate a membership, simply update an existing membership record so that it has a valid PBS uid ('user id' - also known as PBS Account ID).

To do this, use the PATCH endpoint described here: 


Endpoints

If your API client does not support any of the following HTTP methods, you may use the X-HTTP-Method-Override header. Learn more


Base Endpoint
https://mvault.services.pbs.org/api/

Membership:put

Notes: you must define content-type as "application/json"

  1. No need to pass a membership_id via the payload; this is inferred from the PUT URL. e.g. https://mvault.services.pbs.org/api/wkrp/memberships/12345
  2. Passing membership ID explicitly in the JSON payload will return an error.
  3. 404 are returned when there is NO membership data. Do NOT be alarmed. (smile)

Create a Membership 

This section describes the payload format required to create a Membership. (info) Learn how to find your station ID

HTTP Request
PUT https://mvault.services.pbs.org/api/{station_id}/memberships/{membership_id}/

URI Parameters

Parameter name Value Description 
station_idslug Flagship station ID
membership_idstringID of the membership, as supplied by the station
mvault_idstringAuto-generated unique identifier for all MVault memberships. This ID is also stored with transaction and subscription data in TVault and can be used to cross reference data between MVault and TVault for members who have made transactions that went through TVault. This field is read-only.

Payload Parameters

The payload input for the system contains mandatory and optional parameters. The output payload will contain mandatory, optional, and read-only parameters.

  • The mandatory parameters must always be provided.
  • If any parameters are not provided, an HTTP response code will be returned with a message indicating that these fields are required. 
  • The Membership resource will be updated with any optional parameter values, if provided.
  • If optional parameters not provided, the resource will be updated to contain default/empty values for those parameters.
  • The read-only parameters must not be provided. A 400 response status code will be returned, and an error message, indicating that these are not to be provided in the payload.

Create

The table below indicates if parameters are mandatory or optional.

(tick) = True    (error) = False

Parameter nameMandatoryOptionalRead-OnlyHas defaultDefault value
first_name(tick)(error)(error)(error)
last_name(tick)(error)(error)(error)
email(error)(tick)(error)(error)
offer(tick)(error)(error)(error)
notes(error)(tick)(error)(error)
start_date(tick)(error)(error)(error)
expire_date(tick)(error)(error)(error)
create_date(error)(error)(tick)(error)
update_date(error)(error)(tick)(error)
activation_date(error)(error)(tick)(error)
membership_id(error)(error)(tick)(error)
pbs_profile(error)(error)(tick)(error)
status(error)(tick)(error)(tick)On
provisional(error)(tick)(error)(tick)false
additional_metadata(error)(tick)(error)(error)
token(error)(error)(tick)(error)


Membership:get

Returns a single record of a member associated with a valid station ID and membership ID (membership_id). (info) Learn how to find your station ID

HTTP Request
GET https://mvault.services.pbs.org/api/{station_id}/memberships/{membership_id}/

Returns a single record of a member associated with a valid station ID and mvault ID (mvault_id). (info) Learn how to find your station ID

HTTP Request
GET https://mvault.services.pbs.org/api/{station_id}/memberships/by_mvault_id/{mvault_id}/

URI Parameters

NameValueDescription
station_idslugFlagship station ID
membership_idstringID of the membership, as supplied by the station
mvault_idstringAuto-generated unique identifier for all MVault memberships. This ID is also stored with transaction and subscription data in TVault and can be used to cross reference data between MVault and TVault for members who have made transactions that went through TVault. This field is read-only.

Example Output

Output when no users have activated this membership
{
    "first_name": "Laura",
    "last_name": "Alvin",
    "email": "lalvin@allreg.com",
    "phone": null,
    "offer": "koth-passport-offer",
    "notes": "",
    "start_date": "2021-04-13T05:00:00Z",
    "expire_date": "2022-04-13T05:00:00Z",
    "grace_period": "2022-07-12T05:00:00Z",
    "membership_id": "Z000104764",
    "create_date": "2021-04-13T17:49:42Z",
    "update_date": "2021-04-13T17:49:50Z",
    "activation_date": null,
    "status": "On",
    "current_state": {
        "has_access": false,
        "explanation": {
            "status": "On",
            "timing": "within_start_expire_dates",
            "token_activated": false
        }
    },
    "provisional": false,
    "additional_metadata": "",
    "token": "binary-method-colony-select",
    "creator": "Alleg",
    "mvault_id": "3e011bd2-573c-4207-bcf5-46de831019a6",
    "pbs_profile": null
}
Output when a user has activated the membership
{
    "first_name": "Mike",
    "last_name": "Albans",
    "email": "malbans@pbs.org",
    "phone": "703-577-7236",
    "offer": "koth-passport-offer",
    "notes": "",
    "start_date": "2017-05-30T15:25:55Z",
    "expire_date": "2021-02-12T16:25:58Z",
    "grace_period": "2021-05-13T16:25:58Z",
    "membership_id": "koth-testing",
    "create_date": "2017-05-30T15:26:26Z",
    "update_date": "2021-04-13T17:32:05Z",
    "activation_date": "2017-05-30T15:27:39Z",
    "status": "Off",
    "current_state": {
        "has_access": false,
        "explanation": {
            "status": "Off",
            "timing": "within_grace_period",
            "token_activated": true
        }
    },
    "provisional": true,
    "additional_metadata": "",
    "token": "public-cliff-western-next",
    "creator": "malbans@pbs.org",
    "mvault_id": "5e9119db-aedb-4327-b5ca-25747ac0d51c",
    "pbs_profile": {
        "UID": "7f637838-fdf7-4700-b140-2fa788b71816",
        "email": "malbans@pbs.org",
        "first_name": "Mike",
        "last_name": "Albans",
        "birth_date": null,
        "login_provider": "PBS",
        "retrieval_status": {
            "status": 200,
            "message": "Success"
        }
    }
}
Output when a user has activated the membership but the profile service is inaccessible
{ 
    "status": "Off", 
    "last_name": "bar", 
    "create_date": "2014-06-20T07:54:59Z", 
    "offer": "8le9kqtzhj41fg2n", 
    "additional_metadata": "", 
    "membership_id": "bj8cft6prh2gsqlm", 
    "update_date": "2014-06-30T09:16:52Z", 
    "first_name": "foo", 
    "provisional": false, 
    "pbs_profile": { 
        "retrieval_status": { 
            "status": 500, 
            "message": "Retrieval of profile data failed", 
            "UID": "c0d5050f-56a7-bbc4-b82a-a7cb6e683e91", 
        }, 
    }, 
    "activation_date": "2014-08-01T16:10:25Z", 
    "notes": "", 
    "start_date": "2014-06-20T12:57:59Z", 
    "expire_date": "2014-07-20T12:57:59Z", 
    "email": foo@bar.com, 
    "token": "bee-lion-zebra-camel", 
}

HTTP Status Codes

Possible status codes returned by this call are 200, 401, 403, 500. View HTTP response codes 

_________________________________________________________________________________

Membership:deleted

Returns a list of all deleted memberships for a specific station ID. (info) Learn how to find your station ID

HTTP Request
GET https://mvault.services.pbs.org/api/{station_id}/memberships/filter/deleted

URI Parameters

Parameter NameValueDescription
station_idslugFlagship station ID

Example Output

This endpoint can be filtered by pagination.

Membership:deleted
{
    "collection_info": {
        "current_page_number": 1,
        "total_items_count": 7,
        "items_per_page": 50,
        "items_current_page": 7
    },
    "objects": [
        {
            "first_name": "No",
            "last_name": "Offer",
            "email": "hkhal@pbs.org",
            "notes": "",
            "offer": null,
            "start_date": "2021-03-18T18:39:58Z",
            "expire_date": "2021-03-25T18:40:04Z",
            "grace_period": "2021-06-23T18:40:04Z",
            "membership_id": "9191882498241234235",
            "create_date": "2021-03-18T18:40:11Z",
            "update_date": "2021-03-18T18:40:25Z",
            "activation_date": null,
            "status": "On",
            "provisional": true,
            "additional_metadata": "",
            "token": "mouse-mister-equal-writing"
        },
        {
            "first_name": "test",
            "last_name": "hk",
            "email": "",
            "notes": "",
            "offer": null,
            "start_date": "2021-03-15T20:08:07Z",
            "expire_date": "2021-03-25T20:08:10Z",
            "grace_period": "2021-06-23T20:08:10Z",
            "membership_id": "1233123123123123123124234",
            "create_date": "2021-03-15T20:08:28Z",
            "update_date": "2021-03-15T20:08:37Z",
            "activation_date": null,
            "status": "On",
            "provisional": true,
            "additional_metadata": "",
            "token": "plaza-smile-precise-studio"
        },
        {
            "first_name": "test",
            "last_name": "",
            "email": "test@pbs.org",
            "notes": "",
            "offer": null,
            "start_date": "2021-03-05T19:19:50Z",
            "expire_date": "2021-04-09T18:19:56Z",
            "grace_period": "2021-07-08T18:19:56Z",
            "membership_id": "1241242142332",
            "create_date": "2021-03-12T19:20:02Z",
            "update_date": "2021-03-12T19:20:16Z",
            "activation_date": null,
            "status": "On",
            "provisional": true,
            "additional_metadata": "",
            "token": "current-formula-building-prize"
        },
        {
            "first_name": "changed",
            "last_name": "name",
            "email": "test.escu@pbs.org",
            "notes": "12345",
            "offer": "test-offer",
            "start_date": "2021-02-06T12:19:37Z",
            "expire_date": "2021-02-09T12:19:37Z",
            "grace_period": "2021-05-10T12:19:37Z",
            "membership_id": "test123123",
            "create_date": "2021-02-22T11:41:49Z",
            "update_date": "2021-03-03T15:26:02Z",
            "activation_date": "2021-02-08T12:19:37Z",
            "status": "On",
            "provisional": true,
            "additional_metadata": "etc123",
            "token": "ringo-photo-bermuda-breath"
        },
        {
            "first_name": "Hanif",
            "last_name": "Khalid",
            "email": "pbsdonat1@gmail.com",
            "notes": "",
            "offer": null,
            "start_date": "2021-02-02T19:12:04Z",
            "expire_date": "2021-03-02T19:12:04Z",
            "grace_period": "2021-05-31T19:12:04Z",
            "membership_id": "temp-KOTH-c0f172c0-dd2b-4f20-82dd-9c28cff35c97",
            "create_date": "2021-02-02T19:12:04Z",
            "update_date": "2021-02-18T14:22:09Z",
            "activation_date": null,
            "status": "On",
            "provisional": false,
            "additional_metadata": "",
            "token": "salami-purpose-percent-talk"
        },
        {
            "first_name": "Lori",
            "last_name": "Varga",
            "email": "lvarga@3pillarglobal.com",
            "notes": "",
            "offer": "test_lorand_varga_offer",
            "start_date": "2021-01-29T09:27:58Z",
            "expire_date": "2021-01-30T09:28:01Z",
            "grace_period": "2021-04-30T09:28:01Z",
            "membership_id": "test_lorand_varga_membership",
            "create_date": "2021-01-29T09:28:15Z",
            "update_date": "2021-02-12T09:56:29Z",
            "activation_date": "2021-01-29T09:29:54Z",
            "status": "On",
            "provisional": true,
            "additional_metadata": "",
            "token": "isotope-cable-reptile-observe"
        },
        {
            "first_name": "Hans",
            "last_name": "Khalis",
            "email": "hkhalis@pbs.org",
            "notes": null,
            "offer": "koth-passport-offer",
            "start_date": "2020-09-08T20:31:51Z",
            "expire_date": "2021-03-26T20:31:53Z",
            "grace_period": "2021-06-24T20:31:53Z",
            "membership_id": "testing23",
            "create_date": "2020-09-09T20:32:01Z",
            "update_date": "2021-02-03T19:58:38Z",
            "activation_date": null,
            "status": "On",
            "provisional": true,
            "additional_metadata": "",
            "token": "saddle-week-small-style"
        }
    ]

_________________________________________________________________________________

Membership:deleted?since

Returns a list of all deleted memberships for a specific station ID after a specific date and time. (info) Learn how to find your station ID

HTTP Request
GET http://mvault.services.pbs.org/api/{station_id}/memberships/filter/deleted?since=2015-06-07T00:00:00Z

URI Parameters

Parameter NameValueDescription
station_idslugFlagship station ID

Query Parameters

Parameter NameValueDescription
last-updated-sincedatetime

Filter the result, showing only the memberships that have been updated after the specified date. The date should be formatted as an ISO 8601 Date String with UTC. Example:   2014-07-17T00:00:00Z

Example Output

This endpoint can be filtered by pagination.

Membership:deleted
{
    "collection_info": {
        "current_page_number": 1,
        "total_items_count": 1,
        "items_per_page": 50,
        "items_current_page": 1
    },
    "objects": [
        {
            "first_name": "No",
            "last_name": "Offer",
            "email": "hkhalis@pbs.org",
            "notes": "",
            "offer": null,
            "start_date": "2021-03-18T18:39:58Z",
            "expire_date": "2021-03-25T18:40:04Z",
            "grace_period": "2021-06-23T18:40:04Z",
            "membership_id": "9191882498241234235",
            "create_date": "2021-03-18T18:40:11Z",
            "update_date": "2021-03-18T18:40:25Z",
            "activation_date": null,
            "status": "On",
            "provisional": true,
            "additional_metadata": "",
            "token": "mouse-mister-equal-writing"
        }
    ]
}

_________________________________________________________________________________

Membership:list

Returns a list of all members associated with a specific station ID. (info) Learn how to find your station ID

HTTP Request
GET https://mvault.services.pbs.org/api/{station_id}/memberships/

URI Parameters

Parameter NameValueDescription
station_idslugFlagship station ID

Query Parameters

Parameter NameValueDescription
last-updated-sincedatetime

Filter the result, showing only the memberships that have been updated after the specified date. The date should be formatted as an ISO 8601 Date String with UTC. Example:   2014-07-17T00:00:00Z

Example Output

This endpoint can be filtered by pagination.

Membership:list results
{
  "collection_info": {
    "current_page_number": 1,
    "total_items_count": 131936,
    "items_per_page": 50,
    "items_current_page": 50,
    "next_page_url": "https://mvault.services.pbs.org/api/weta/memberships/?page=2"
  },
  "objects": [
    {
      "grace_period": "2016-10-19T18:38:24Z",
      "update_date": "2016-04-21T18:38:40Z",
      "first_name": "Nelson",
      "last_name": "Rogers",
      "create_date": "2016-04-21T18:38:40Z",
      "offer": "test-weta-offer-staging",
      "notes": null,
      "current_state": {
        "explanation": {
          "status": "On",
          "timing": "within_start_expire_dates",
          "token_activated": false
        },
        "has_access": false
      },
      "membership_id": "prince123",
      "start_date": "2016-04-21T18:38:21Z",
      "status": "On",
      "token": "premium-analog-tendency-present",
      "additional_metadata": "",
      "activation_date": null,
      "provisional": true,
      "expire_date": "2016-07-21T18:38:24Z",
      "pbs_profile": null,
      "email": "prince@purplerain.org"
     }
  ]
}

Memberships/?last_updated_since

The last_updated_since parameter returns a list of all members associated with a specific station ID whose records have been updated after a specified date. (info) Learn how to find your station ID

HTTP request
GET https://mvault.services.pbs.org/api/f3842586-2c40-43fa-a79f-841fd5f2b9cb/memberships/?last_updated_since=2014-01-17T00:00:00Z
Memberships updated since January 17, 2014
{
  "collection_info": {
    "current_page_number": 1,
    "total_items_count": 131936,
    "items_per_page": 50,
    "items_current_page": 50,
    "next_page_url": "https://mvault.services.pbs.org/api/weta/memberships/?last_updated_since=2014-01-17T00:00:00Z&page=2"
  },
  "objects": [
    {
      "grace_period": "2016-10-19T18:38:24Z",
      "update_date": "2016-04-21T18:38:40Z",
      "first_name": "Nelson",
      "last_name": "Rogers",
      "create_date": "2016-04-21T18:38:40Z",
      "offer": "test-weta-offer-staging",
      "notes": null,
      "current_state": {
        "explanation": {
          "status": "On",
          "timing": "within_start_expire_dates",
          "token_activated": false
        },
        "has_access": false
      },
      "membership_id": "prince123",
      "start_date": "2016-04-21T18:38:21Z",
      "status": "On",
      "token": "premium-analog-tendency-present",
      "additional_metadata": "",
      "activation_date": null,
      "provisional": true,
      "expire_date": "2016-07-21T18:38:24Z",
      "pbs_profile": null,
      "email": "prince@weta.org"
      }
   ]
}

Paginate

To request the second page of all WKRP (station_id: f3842586-2c40-43fa-a79f-841fd5f2b9cb) memberships updated after January 17, 2014:

HTTP request
GET https://mvault.services.pbs.org/api/f3842586-2c40-43fa-a79f-841fd5f2b9cb/memberships/?last_updated_since=2014-01-17T00:00:00Z&page=2
Requesting second page
{
  "collection_info": {
    "current_page_number": 2,
    "total_items_count": 131936,
    "items_per_page": 50,
    "items_current_page": 50,
    "next_page_url": "https://mvault.services.pbs.org/api/weta/memberships/?last_updated_since=2014-01-17T00:00:00Z&page=3",
    "previous_page_url": "https://mvault.services.pbs.org/api/weta/memberships/?last_updated_since=2014-01-17T00:00:00Z&page=1"
  },
  "objects": [
    {
      "grace_period": "2017-05-27T05:00:00Z",
      "update_date": "2016-03-01T15:07:58Z",
      "first_name": "Jean",
      "last_name": "Green",
      "create_date": "2016-03-01T15:07:58Z",
      "offer": "test-mvod-offer-1",
      "notes": "",
      "current_state": {
        "explanation": {
          "status": "On",
          "timing": "within_start_expire_dates",
          "token_activated": false
        },
        "has_access": false
      },
      "membership_id": "MV_55226180",
      "start_date": "2016-03-01T13:00:53Z",
      "status": "On",
      "token": "ninja-bagel-support-sensor",
      "additional_metadata": "",
      "activation_date": null,
      "provisional": false,
      "expire_date": "2017-02-26T05:00:00Z",
      "pbs_profile": null,
      "email": "jgreen@gmail.com"
      }
   ]
}

HTTP Status Codes

Possible status codes returned are 200, 401, 403 and 500.  httpresponsecodes.

Memberships:active?

The active endpoint returns a list of active memberships per station. 'Active' is any record that has start and expire dates that fall within the current date and Status=On. (Note: Activation Date status is not considered as part of the criteria.)

Active memberships can be filtered a variety of ways:

(1) By email address: returns a list of all active members associated with a specific email address.(info) Learn how to find your station ID

(2) By time-based windowing using start_date and end_date params. 

(info) Learn how email is validated

URI Parameters

Parameter NameValueDescriptionRequired?
station_idstringFlagship station IDY
email addressstringEmail address of the memberN
start_date, end_datedatetime

Filter active memberships, based on a time-window. Both parameters must be used together. Time is on a 24H clock. 00:00:00 being midnight.


N
Endpoint
GET https://mvault.services.pbs.org/api/{station_id}/memberships/filter/active?email={email address}
Example: email filtering
https://mvault.services.pbs.org/api/f3842586-2c40-43fa-a79f-841fd5f2b9cb/memberships/filter/active?email=jdoe@wkrp.org
Example: time-based filtering
https://mvault.services.pbs.org/api/KOTH/memberships/filter/active/?start_date=2017-09-01T00:00:00Z&end_date=2017-09-30T00:00:00Z
Result if member IS active
{
  "collection_info": {
    "current_page_number": 1,
    "total_items_count": 1,
    "items_per_page": 50,
    "items_current_page": 1
  },
  "objects": [
    {
      "grace_period": "2017-07-13T19:46:29Z",
      "update_date": "2016-04-14T19:52:11Z",
      "first_name": "Jilly",
      "last_name": "Doe",
      "create_date": "2016-02-13T16:49:51Z",
      "offer": "test-mvod-offer-1",
      "notes": "",
      "current_state": {
   		"explanation": {
      	"status": "Off",
      	"timing": "within_start_expire_dates",
      	"token_activated": true
      },
      "has_access": false
  },
      "membership_id": "MV_937975",
      "start_date": "2016-01-27T05:00:00Z",
      "status": "On",
      "token": "finance-wheel-jungle-active",
      "additional_metadata": "{\"roi_last_change_date\":\"2016-04-14T19:52:11Z\"}",
      "activation_date": 2015-01-27T05:00:00Z,
      "provisional": false,
      "expire_date": "2017-04-14T19:46:29Z",
      "pbs_profile": null,
      "email": "jdoe@wkrp.org"
    }
  ]
}
Result if member is NOT active
{
    "errors": "No resource found"
} 

_____________________________________________________________________________

Memberships:station/email

The station and email parameters return a single member based upon their station ID and email address. Unlike the Memberships:active?email endpoint, this endpoint does not take member status into consideration — just whether or not the email address exists in MVault. 

(info) Learn how to find your station ID

(info) Learn how email is validated

URI Parameters

Parameter NameValueDescription
station_idstringFlagship station ID
email addressstringEmail address of the registered member
Endpoint
https://mvault.services.pbs.org/api/{station_id}/memberships/filter/email/{email address}/
Example
https://mvault.services.pbs.org/api/f3842586-2c40-43fa-a79f-841fd5f2b9cb/memberships/filter/email/jdoe@wkrp.org/


Result if member IS active
{
    "collection_info": {
        "current_page_number": 1,
        "total_items_count": 1,
        "items_per_page": 50,
        "items_current_page": 1
    },
    "objects": [
        {
            "grace_period": "2016-11-24T16:58:35Z",
            "update_date": "2015-08-18T14:45:30Z",
            "first_name": "John",
            "last_name": "Doe",
            "create_date": "2015-02-06T17:59:28Z",
            "offer": "mvod",
            "notes": "",
			"current_state": {
   			  "explanation": {
      		  "status": "Off",
      		  "timing": "within_start_expire_dates",
      		  "token_activated": true
      		},
      		"has_access": false
  },
            "membership_id": "123-jdoe",
            "start_date": "2015-02-06T17:58:29Z",
            "status": "On",
            "token": "cinema-galaxy-pen-grass",
            "additional_metadata": "",
            "activation_date": "2015-02-09T13:32:06Z",
            "provisional": true,
            "expire_date": "2016-08-26T16:58:35Z",
            "pbs_profile": {
                "first_name": "John",
                "last_name": "Doe",
                "UID": "fae84259-c110-40d9-acae-31ece9b6c481",
                "birth_date": null,
                "retrieval_status": {
                    "status": 200,
                    "message": "Success"
                },
                "email": "jdoe@wkrp.org",
                "login_provider": "PBS"
            },
            "email": "jdoe@wkrp.org"
        }
    ]
}


_____________________________________________________________________________

Membership:list_activated

Returns a list of all activated members associated with a specific station ID. activated-since (info) Learn how to find your station ID

HTTP Request
GET https://mvault.services.pbs.org/api/{station_id}/memberships/filter/activated/

URI Parameters

Parameter NameValueDescription
station_idslugFlagship station ID

Query Parameters

Parameter NameValueDescription
since activated-sincedatetime

Filter the result, showing only the memberships that have been activated after the specified date. The date should be formatted as an ISO 8601 Date String with UTC. Example:   2014-07-17T00:00:00Z

page paginatedinteger

Show the results on a specific page. See the Pagination section for more details.

page_size paginatedintegerSpecify number of objects for current page. See the Pagination section for more details.
exclude_profile_data exclude_profile_dataintegerExclude PBS profile user data eliminating external calls towards profile-service API

Example Output

The response for a request made to this endpoint will be pagination.

An example of a response for a request made without any query parameters
{
  "collection_info": {
    "current_page_number": 1,
    "total_items_count": 4,
    "items_per_page": 50,
    "items_current_page": 4
  },
  "objects": [
    {
      "grace_period": "2017-05-10T08:40:32Z",
      "update_date": "2016-04-13T13:10:42Z",
      "first_name": "Vinny",
      "last_name": "Trif",
      "create_date": "2016-04-13T13:07:21Z",
      "offer": "weta-passport-offer",
      "notes": "",
      "current_state": {
        "explanation": {
          "status": "Off",
          "timing": "within_start_expire_dates",
          "token_activated": true
        },
        "has_access": false
      },
      "membership_id": "service1",
      "start_date": "2014-09-05T08:40:28Z",
      "status": "Off",
      "token": "film-anteater-igloo-press",
      "additional_metadata": "",
      "activation_date": "2016-04-13T13:09:14Z",
      "provisional": false,
      "expire_date": "2017-02-09T08:40:32Z",
      "pbs_profile": {
        "first_name": "Vinny",
        "last_name": "Trif",
        "UID": "45c55336-cdea-4e6a-ab64-b479baaa6c34",
        "birth_date": null,
        "retrieval_status": {
          "status": 200,
          "message": "Success"
        },
        "email": "vtrif@3pill.com",
        "login_provider": "Google"
      },
      "email": "vtrif@gmail.com"    
    }
  ]
}

Membership:list_activated/?since

The since parameter returns a list of all activated members associated with a specific station ID after a specified date. (info) Learn how to find your station ID

HTTP Request
GET https://mvault.services.pbs.org/api/f3842586-2c40-43fa-a79f-841fd5f2b9cb/memberships/filter/activated/?since=2014-07-17T00:00:00Z
Members activated after July 17, 2014
{
  "collection_info": {
    "current_page_number": 1,
    "total_items_count": 4,
    "items_per_page": 50,
    "items_current_page": 4
  },
  "objects": [
    {
      "grace_period": "2017-05-10T08:40:32Z",
      "update_date": "2016-04-13T13:10:42Z",
      "first_name": "John",
      "last_name": "Dill",
      "create_date": "2016-04-13T13:07:21Z",
      "offer": "weta-passport-offer",
      "notes": "",
      "current_state": {
        "explanation": {
          "status": "Off",
          "timing": "within_start_expire_dates",
          "token_activated": true
        },
        "has_access": false
      },
      "membership_id": "service1",
      "start_date": "2014-09-05T08:40:28Z",
      "status": "Off",
      "token": "film-anteater-igloo-press",
      "additional_metadata": "",
      "activation_date": "2016-04-13T13:09:14Z",
      "provisional": false,
      "expire_date": "2017-02-09T08:40:32Z",
      "pbs_profile": {
        "first_name": "John",
        "last_name": "Dill",
        "UID": "45c55336-cdea-4e6a-ab64-b479baaa6c34",
        "birth_date": null,
        "retrieval_status": {
          "status": 200,
          "message": "Success"
        },
        "email": "jdill@pillar.com",
        "login_provider": "Google"
      },
      "email": "jdilwl@pillar.com"
    },
    {
      "grace_period": "2016-05-18T08:52:30Z",
      "update_date": "2015-12-02T08:45:28Z",
      "first_name": "Dan",
      "last_name": "Popper",
      "create_date": "2015-11-25T08:52:44Z",
      "offer": "test-mvod-offer-1",
      "notes": "",
      "current_state": {
        "explanation": {
          "status": "On",
          "timing": "within_grace_period",
          "token_activated": true
        },
        "has_access": true
      },
      "membership_id": "danamaliamircea",
      "start_date": "2015-11-25T08:52:26Z",
      "status": "On",
      "token": "store-cat-cork-local",
      "additional_metadata": "",
      "activation_date": "2015-11-25T08:53:25Z",
      "provisional": true,
      "expire_date": "2016-02-18T08:52:30Z",
      "pbs_profile": {
        "first_name": "Dan",
        "last_name": "Popper",
        "UID": "170700a0-7b13-4447-96e0-75e49e6f1c6e",
        "birth_date": null,
        "retrieval_status": {
          "status": 200,
          "message": "Success"
        },
        "email": "dan@global.com",
        "login_provider": "PBS"
      },
      "email": "dan@global.com"
    }
  ]
}

Membership:list_activated/?exclude_profile_data

The exclude_profile_data parameter excludes PBS profile user data eliminating external calls towards profile-service API. Only UID will be returned.

HTTP Request
GET https://mvault.services.pbs.org/api/f3842586-2c40-43fa-a79f-841fd5f2b9cb/memberships/filter/activated/?exclude_profile_data=1
Members activated after July 17, 2014
{
  "collection_info": {
    "current_page_number": 1,
    "total_items_count": 4,
    "items_per_page": 50,
    "items_current_page": 4
  },
  "objects": [
    {
      "grace_period": "2017-05-10T08:40:32Z",
      "update_date": "2016-04-13T13:10:42Z",
      "first_name": "John",
      "last_name": "Dill",
      "create_date": "2016-04-13T13:07:21Z",
      "offer": "weta-passport-offer",
      "notes": "",
      "current_state": {
        "explanation": {
          "status": "Off",
          "timing": "within_start_expire_dates",
          "token_activated": true
        },
        "has_access": false
      },
      "membership_id": "service1",
      "start_date": "2014-09-05T08:40:28Z",
      "status": "Off",
      "token": "film-anteater-igloo-press",
      "additional_metadata": "",
      "activation_date": "2016-04-13T13:09:14Z",
      "provisional": false,
      "expire_date": "2017-02-09T08:40:32Z",
      "pbs_profile": {
        "UID": "45c55336-cdea-4e6a-ab64-b479baaa6c34",
      },
      "email": "jdilwl@pillar.com"
    },
    {
      "grace_period": "2016-05-18T08:52:30Z",
      "update_date": "2015-12-02T08:45:28Z",
      "first_name": "Dan",
      "last_name": "Popper",
      "create_date": "2015-11-25T08:52:44Z",
      "offer": "test-mvod-offer-1",
      "notes": "",
      "current_state": {
        "explanation": {
          "status": "On",
          "timing": "within_grace_period",
          "token_activated": true
        },
        "has_access": true
      },
      "membership_id": "danamaliamircea",
      "start_date": "2015-11-25T08:52:26Z",
      "status": "On",
      "token": "store-cat-cork-local",
      "additional_metadata": "",
      "activation_date": "2015-11-25T08:53:25Z",
      "provisional": true,
      "expire_date": "2016-02-18T08:52:30Z",
      "pbs_profile": {
        "UID": "170700a0-7b13-4447-96e0-75e49e6f1c6e",
      },
      "email": "dan@global.com"
    }
  ]
}

Paginate

To request the second page of all memberships activated for the station WETA since July 17, 2014:

HTTP request
GET https://mvault.services.pbs.org/api/f3842586-2c40-43fa-a79f-841fd5f2b9cb/memberships/filter/activated/?since=2014-07-17T00:00:00Z&page=2


To request the second page of all memberships activated for the station WETA since July 17, 2014 with a specific number of objects for the current page:

HTTP request
GET https://mvault.services.pbs.org/api/f3842586-2c40-43fa-a79f-841fd5f2b9cb/memberships/filter/activated/?since=2014-07-17T00:00:00Z&page=2&page_size=100

   

   

Requesting second page
{     
    "collection_info": {         
        "current_page_number": 2,         
        "total_items_count": 115,         
        "items_per_page": 100,         
        "items_current_page": 15,         
        "next_page_url": "https://mvault.services.pbs.org/api/f3842586-2c40-43fa-a79f-841fd5f2b9cb/memberships/?last_updated_since=2014-01-17T00:00:00Z&page=3",         "previous_page_url": "https://mvault.services.pbs.org/api/f3842586-2c40-43fa-a79f-841fd5f2b9cb/memberships/?last_updated_since=2014-01-17T00:00:00Z&page=1"     },     
    "objects": [
    {
      "grace_period": "2017-05-10T08:40:32Z",
      "update_date": "2016-04-13T13:10:42Z",
      "first_name": "Jilly",
      "last_name": "Dell",
      "create_date": "2016-04-13T13:07:21Z",
      "offer": "weta-passport-offer",
      "notes": "",
      "current_state": {
        "explanation": {
          "status": "Off",
          "timing": "within_start_expire_dates",
          "token_activated": true
        },
        "has_access": false
      },
      "membership_id": "service1",
      "start_date": "2014-09-05T08:40:28Z",
      "status": "Off",
      "token": "film-good-igloo-press",
      "additional_metadata": "",
      "activation_date": "2016-04-13T13:09:14Z",
      "provisional": false,
      "expire_date": "2017-02-09T08:40:32Z",
      "pbs_profile": {
        "first_name": "Jilly",
        "last_name": "Dell",
        "UID": "45c55336-cdea-4e6a-ab64-b479baaa6c34",
        "birth_date": null,
        "retrieval_status": {
          "status": 200,
          "message": "Success"
        },
        "email": "jdell@pillar.com",
        "login_provider": "Google"
      },
      "email": "jdelpl@pillar.com"
    }
  ]
}

HTTP Status Codes

Possible status codes returned are: 200, 401, 403 and 500. httpresponsecodes. 

_______________________________________________________________________________

Membership:list_provisional

Returns a list of all members associated with a specific station who have been granted access but have not been verified by the station. (info) Learn how to find your station ID

HTTP Request
GET https://mvault.services.pbs.org/api/{station_id}/memberships/filter/provisional/

URI Parameters

Parameter NameValueDescription
station_idslugFlagship station ID

Query Parameters

Parameter NameValueDescription
sincedatetime

Filter the result, showing only the provisional memberships, created after the date specified here.

pageinteger

Show the results on a specific page. See the pagination section for more details.

Example Output

The response for a request made to this endpoint will be pagination.

Response for a request made without any query parameters
{
    "collection_info": {
        "current_page_number": 1,
        "total_items_count": 15,
        "items_per_page": 50,
        "items_current_page": 15
    },
    "objects": [
        {
          "status": "On",
          "last_name": "",
          "create_date": "2015-01-29T15:31:36Z",
          "offer": "smoke_offer",
          "additional_metadata": "",
          "activation_date": null,
          "pbs_profile": null,
          "update_date": "2015-01-29T15:31:37Z",
          "first_name": "",
          "provisional": true,
          "notes": "\r",
		  "current_state": {
            "explanation": {
              "status": "On",
              "timing": "within_start_expire_dates",
              "token_activated": false
          },
          "has_access": false
      },
            "membership_id": "smoke_membership",
            "start_date": "2015-01-01T16:00:00Z",
            "token": "alias-saddle-sound-table",
            "expire_date": "2018-01-01T16:00:00Z",
            "email": ""
        },
    ]
} 

Membership:list_provisional/?since

The since parameter returns a list of all provisional members associated with a specific station after a specified date. Only members with provisional "true" are returned. (info) Learn how to find your station ID

HTTP request
https://mvault.services.pbs.org/api/f3842586-2c40-43fa-a79f-841fd5f2b9cb/memberships/filter/provisional/?since=2014-07-17T00:00:00Z&page=1
All provisional members since July 17, 2014
{
  "collection_info": {
    "current_page_number": 1,
    "total_items_count": 250,
    "items_per_page": 50,
    "items_current_page": 50,
    "next_page_url": "https://mvault.services.pbs.org/api/weta/memberships/filter/provisional/?since=2014-07-17T00:00:00Z&page=2"
  },
  "objects": [
    {
      "grace_period": "2016-10-19T18:38:24Z",
      "update_date": "2016-04-21T18:38:40Z",
      "first_name": "Nelson",
      "last_name": "Rogers",
      "create_date": "2016-04-21T18:38:40Z",
      "offer": "test-weta-offer-staging",
      "notes": null,
      "current_state": {
        "explanation": {
          "status": "On",
          "timing": "within_start_expire_dates",
          "token_activated": false
        },
        "has_access": false
      },
      "membership_id": "prince123",
      "start_date": "2016-04-21T18:38:21Z",
      "status": "On",
      "token": "premium-analog-tendency-present",
      "additional_metadata": "",
      "activation_date": null,
      "provisional": true,
      "expire_date": "2016-07-21T18:38:24Z",
      "pbs_profile": null,
      "email": "prince@weta.org"
    }
  ]
}
 

Paginate

To request the second page of all the provisional memberships for the WETA station since July 17, 2014:

HTTP request
GET https://mvault.services.pbs.org/api/f3842586-2c40-43fa-a79f-841fd5f2b9cb/memberships/filter/provisional/?since=2014-07-17T00:00:00Z&page=2
Requesting second page
{
  "collection_info": {
    "current_page_number": 2,
    "total_items_count": 250,
    "items_per_page": 50,
    "items_current_page": 50,
    "next_page_url": "https://mvault.services.pbs.org/api/weta/memberships/filter/provisional/?since=2014-07-17T00:00:00Z&page=3",
    "previous_page_url": "https://mvault.services.pbs.org/api/weta/memberships/filter/provisional/?since=2014-07-17T00:00:00Z&page=1"
  },
  "objects": [
    {
      "grace_period": "2016-12-21T18:15:06Z",
      "update_date": "2015-11-13T15:34:41Z",
      "first_name": "Jay",
      "last_name": "Son",
      "create_date": "2015-11-13T15:34:41Z",
      "offer": "test-mvod-offer-1",
      "notes": "PASSPORT ELIGIBLE GRANDFATHERED PRIOR TO LAUNCH",
      "current_state": {
        "explanation": {
          "status": "On",
          "timing": "within_start_expire_dates",
          "token_activated": false
        },
        "has_access": false
      },
      "membership_id": "2483293",
      "start_date": "2015-10-05T18:15:06Z",
      "status": "On",
      "token": "mystery-lion-easy-noise",
      "additional_metadata": "",
      "activation_date": null,
      "provisional": true,
      "expire_date": "2016-09-22T18:15:06Z",
      "pbs_profile": null,
      "email": "json@aol.com"
     }
  ]
}

HTTP Status Codes

Possible status codes returned are: 200, 401, 403 and 500. httpresponsecodes. 

_________________________________________________________________________________

Membership:list_grace_period

Extends a member’s access to MVOD content for 90 days after their expire date. (info) Learn how to find your station ID

Notes about grace_period:

  • The grace period is automatically calculated within MVault, based on the membership Expire Date that is set or updated by the station.
  • A member's actual Expire Date will not be changed; the grace period will be handled separately on the back-end.
  • For reference, the grace period end date will be presented as a read-only field within the MVault console.
  • While a member will continue to have MVOD access for 90 days following their Expire Date, they will not be considered  “active” members during this time.
  • Within the MVault API, the “grace_period” field will represent the end date/time.
  • Note: Users are able to activate during the Grace Period. (Use case: A user never activated Passport during their year of eligibility, then decides to do so while in Grace Period.)
  • Note: Grace period is simply a calculation based on the selected Expire date. It does not care about the value of Status or Activation Date. Grace Period does not provide access, it will simply extend it for those members who have it, for 90 days after their Expire Date.
HTTP Request
GET https://mvault.services.pbs.org/api/{station_id}/memberships/filter/grace_period/

URI Parameters

Parameter nameValueDescription
station_idslugFlagship station ID

Example Output

The response for a request made to this endpoint will be pagination.

{
  "collection_info": {
    "current_page_number": 1,
    "total_items_count": 3895,
    "items_per_page": 50,
    "items_current_page": 50,
    "next_page_url": "https://mvault.services.pbs.org/api/weta/memberships/filter/grace_period/?page=2"
  },
  "objects": [
    {
      "grace_period": "2016-05-10T05:00:00Z",
      "update_date": "2016-02-26T19:29:37Z",
      "first_name": "Mike",
      "last_name": "Smith",
      "create_date": "2016-01-29T19:07:29Z",
      "offer": "test-mvod-offer-1",
      "notes": "",
      "current_state": {
        "explanation": {
          "status": "On",
          "timing": "within_grace_period",
          "token_activated": false
        },
        "has_access": false
      },
      "membership_id": "MV_1378313",
      "start_date": "2015-10-05T18:15:06Z",
      "status": "On",
      "token": "teacher-flute-orange-vortex",
      "additional_metadata": "",
      "activation_date": null,
      "provisional": false,
      "expire_date": "2016-02-10T05:00:00Z",
      "pbs_profile": null,
      "email": "msmith@yahoo.com"
      }
    ]
} 

_________________________________________________________________________________

Membership:list_token

Search for users by token for a particular station. (info) Learn how to find your station ID

HTTP Request
GET https://mvault.services.pbs.org/api/{station_id}/memberships/filter/token/{token}/

URI Parameters

Parameter nameValueDescription
station_idslugFlagship station ID
tokenstringUser's activation token

Example Output

The response for a request made to this endpoint will be pagination.

{
  "grace_period": "2016-08-25T04:00:00Z",
  "update_date": "2016-04-27T11:34:00Z",
  "first_name": "Howard",
  "last_name": "Horse",
  "create_date": "2016-03-02T00:21:25Z",
  "offer": "weta-passport-offer",
  "notes": "",
  "current_state": {
    "explanation": {
      "status": "On",
      "timing": "within_start_expire_dates",
      "token_activated": true
    },
    "has_access": true
  },
  "membership_id": "MV_1337868",
  "start_date": "2015-10-05T18:15:06Z",
  "status": "On",
  "token": "bread-smudge-sled-annex",
  "additional_metadata": "",
  "activation_date": "2016-04-27T11:34:00Z",
  "provisional": false,
  "expire_date": "2016-05-27T04:00:00Z",
  "pbs_profile": {
    "first_name": "howard",
    "last_name": "horse",
    "UID": "e9d9a866-176c-4899-bcf2-b0b53ee137be",
    "birth_date": null,
    "retrieval_status": {
      "status": 200,
      "message": "Success"
    },
    "email": "hhorse@verizon.net",
    "login_provider": "PBS"
  },
  "email": "hhorse@verizon.net"
}

_________________________________________________________________________________

Membership:list_uid

Search for users by UID for a particular station. (info) Learn how to find your station ID

HTTP Request
GET https://mvault.services.pbs.org/api/{station_id}/memberships/filter/uid/{uid}/

URI Parameters

Parameter nameValueDescription
station_idslugFlagship station ID
uidguidUser profile ID

Example Output

The response for a request made to this endpoint will be paginated.

[
  {
    "grace_period": "2017-07-24T04:00:00Z",
    "update_date": "2016-04-27T03:10:00Z",
    "first_name": "Elke",
    "last_name": "Vonn",
    "create_date": "2016-04-20T21:23:32Z",
    "offer": "weta-passport-offer",
    "notes": "",
    "current_state": {
      "explanation": {
        "status": "On",
        "timing": "within_start_expire_dates",
        "token_activated": true
      },
      "has_access": true
    },
    "membership_id": "MV_55187567",
    "start_date": "2015-10-05T18:15:06Z",
    "status": "On",
    "token": "octopus-relax-view-nominal",
    "additional_metadata": "{\"roi_last_change_date\":\"2016-04-25T19:03:16Z\"}",
    "activation_date": "2016-04-27T03:10:00Z",
    "provisional": false,
    "expire_date": "2017-04-25T04:00:00Z",
    "pbs_profile": {
      "first_name": "elke",
      "last_name": "vonn",
      "UID": "106454fa-09ba-4309-81b3-27b3f47d3f4d",
      "birth_date": null,
      "retrieval_status": {
        "status": 200,
        "message": "Success"
      },
      "email": "evonn@gmail.com",
      "login_provider": "Google"
    },
    "email": "evnonn@yahoo.com"
  }
]

_________________________________________________________________________________

Membership:update

The Membership:update endpoint has two different functions:

  1. Create - Create an entirely new membership record or make edits to an existing membership record.
  2. Update - Change the membership ID while leaving rest of record unchanged.

Edit a Membership 

This section describes the payload format required to edit a Membership. (info) Learn how to find your station ID

HTTP Request
PUT https://mvault.services.pbs.org/api/{station_id}/memberships/{membership_id}/
HTTP Request
PUT https://mvault.services.pbs.org/api/{station_id}/memberships/by_mvault_id/{mvault_id}/

URI Parameters

Parameter name Value Description 
station_idslug Flagship station ID
membership_idstringID of the membership, as supplied by the station
mvault_idstringAuto-generated unique identifier for all MVault memberships. This ID is also stored with transaction and subscription data in TVault and can be used to cross reference data between MVault and TVault for members who have made transactions that went through TVault. This field is read-only.

Payload Parameters

The payload input for the system contains mandatory and optional parameters . The output payload will contain mandatory, optional, and read-only parameters.

  • The mandatory parameters must always be provided.
  • If any parameters are not provided, a httpresponsecodes will be returned with a message indicating that these fields are required. 
  • The Membership resource will be updated with any optional parameter values, if provided.
  • If optional parameters not provided, the resource will be updated to contain default/empty values for those parameters.
  • The read-only parameters must not be provided. A 400 response status code will be returned, and an error message, indicating that these are not to be provided in the payload.

Update

The table below indicates if parameters are mandatory or optional.

(tick) = True    (error) = False

Parameter nameMandatoryOptionalRead-OnlyHas defaultDefault value
first_name(tick)(error)(error)(error)
last_name(tick)(error)(error)(error)
email(error)(tick)(error)(error)
offer(tick)(error)(error)(error)
notes(error)(tick)(error)(error)
start_date(tick)(error)(error)(error)
expire_date(tick)(error)(error)(error)
create_date(error)(error)(tick)(error)
update_date(error)(error)(tick)(error)
activation_date(error)(error)(tick)(error)
membership_id(error)(error)(tick)(error)
pbs_profile(error)(error)(tick)(error)
status(error)(tick)(error)(tick)On
provisional(error)(tick)(error)(tick)false
additional_metadata(error)(tick)(error)(error)
token(error)(error)(tick)(error)

  

There currently is no API to support retrieval of offer IDs.

Update

Update (edit) differs slightly from Create, however, the response is the same for success and failure. In case the membership_id specified in the URL exists, it will be modified. If the membership_id parameter is being modified, this could collide with the membership_id of another Membership. In this case, the response will contain an error message indicating that this collision occurred.

Valid Request
PUT /api/weta/memberships/bj8cft6prh2gsqlm/ 
Content-Type: application/json 
 
{     
     "status": "Off",     
     "last_name": "foo",     
     "offer": "8le9kqtzhj41fg2n",     
     "additional_metadata": "",     
     "membership_id": "bj8cft6prh2gsqlm",     
     "first_name": "bar",     
     "provisional": false,     
     "notes": "",     
     "start_date": "2014-06-20T12:57:59Z",     
     "expire_date": "2014-07-20T12:57:59Z",     
     "email": bar@foo.com 
}
Output HTTP status code: 200
{ 
	"status":"Off", 
	"last_name":"foo", 
	"create_date":"2014-06-20T07:54:59Z", 
	"offer":"8le9kqtzhj41fg2n", 
	"additional_metadata":"", 
	"membership_id":"bj8cft6prh2gsqlm", 
	"activation_date":null, 
	"update_date":"2014-07-01T16:10:25Z", 
	"first_name":"bar", 
	"provisional":false, 
	"notes":"", 
	"start_date":"2014-06-20T12:57:59Z", 
	"expire_date":"2014-07-20T12:57:59Z", 
	"email":"bar@foo.com" 	
	"token":"bee-lion-zebra-camel" 
}
Invalid payload example 1 - too many fields specified
{
    "status":"Off",
    "last_name":"foo",
    "create_date":"2014-06-20T07:54:59Z",
    "offer":"8le9kqtzhj41fg2n",
    "additional_metadata":"",
    "activation_date":null,
    "update_date":"2014-06-30T09:16:52Z",
    "first_name":"bar",
    "provisional":false,
    "notes":"",
    "start_date":"2014-06-20T12:57:59Z",
    "expire_date":"2014-07-20T12:57:59Z",
    "email":"bar@foo.com"
 }
Output HTTP status code: 400
{
    "errors": 
    {
    	"__all__": "The following fields can't be updated and shouldn't be specified: ['update_date', 'activation_date', 'create_date']."
    }
}
Invalid payload example 2 - too few fields specified HTTP status code: 400
{
    "status":"Off",
    "offer":"8le9kqtzhj41fg2n",
    "additional_metadata":"",
    "provisional":false,
    "notes":"",
    "start_date":"2014-06-20T12:57:59Z",
    "expire_date":"2014-07-20T12:57:59Z",
    "email":"bar@foo.com"    
}
Output HTTP status code: 400
{
    "errors": {
        "first_name": [
            "This field is required."
        ],
        "last_name": [
            "This field is required."
        ],
    }
}
Invalid payload example 3 - invalid format for the fields
{
    "status":"Off",
    "last_name":"foo",
    "offer":"8le9kqtzhj41fg2nbvbvb",
    "additional_metadata":"",
    "first_name":"bar",
    "provisional":false,
    "notes":"",
    "start_date":"2014/06/20",
    "expire_date":"2014/07/20T12:57:59Z"
    "email":"bar@foo.com"
}
Output HTTP status code: 400
{
    "errors":  
    {
        "expire_date":[
	     "Enter a valid date/time."
	],
        "start_date":[
	     "Enter a valid date/time."
	],
        "offer":[
	     "Select a valid choice.  That choice is not one of the available choices."
	]
    }
}

HTTP Status Codes

Possible status codes returned are 200, 401, 403, 404, 500. httpresponsecodes 

 _________________________________________________________________________________  

Update the membership ID for a Membership (PATCH)

This section describes the payload format required to update the membership ID for a Membership . No response body is returned by this endpoint. 

If the Membership resource’s state needs to be investigated, we recommend a call to the GET endpoint. (info) Learn how to find your station ID

Learn how MVault handles two membership records with identical UIDs


The following example is executed using the Google Postman app.

Figure 1 

Figure 2 

  • If the call executed successfully, the Status displays 200 OK.  The time it took to process is also displayed (Figure 3). 

Figure 3 

  • Check the new Membership ID in mvault.console.pbs.org (Figure 4).

Figure 4 

 

HTTP Request
PATCH https://mvault.services.pbs.org/api/{station_id}/memberships/{membership_id}/

Update the mvault ID for a Membership (PATCH)

This section describes the payload format required to update the mvault ID for a Membership . No response body is returned by this endpoint. 

HTTP Request
PATCH https://mvault.services.pbs.org/api/{station_id}/memberships/by_mvault_id/{mvault_id}/

URI Parameters

Parameter name Value Description 
station_id slug Flagship station ID
membership_idstringID of the membership, as supplied by the station 
mvault_idstringAuto-generated unique identifier for all MVault memberships. This ID is also stored with transaction and subscription data in TVault and can be used to cross reference data between MVault and TVault for members who have made transactions that went through TVault. This field is read-only.

Payload Parameters

Only specify fields in the payload that you are changing.

Parameter name 

first_name

uid
last_name membership_id
email status
phone703-555-1212
offer provisional
notes additional_metadata
start_date YYYY-MM-DDTHH:MM:SSZ
expire_date YYYY-MM-DDTHH:MM:SSZ

The PATCH update differs from PUT in that it doesn’t require specifying all fields and only takes into consideration the ones that are specified when doing the update. This makes it easy to update only a few fields without having to explicitly provide unchanged values for unchanged fields.

Payload Example

Valid Request
PATCH /api/f3842586-2c40-43fa-a79f-841fd5f2b9cb/memberships/bj8cft6prh2gsqlm/ Content-Type: application/json 
 
{   "membership_id": "bj8cft6prh2gsqlm", 
    "uid": "c476e7f8-c053-4352-a27a-2fc0aa972f07",
    "email": "new@email.com" 
}

No response body will be returned by this endpoint. If the Membership resource’s state needs to be investigated, we recommend a call to the GET endpoint.


Output upon successful update
HTTP/1.1 200 No Content Location: https://mvault.services.pbs.org/api/weta/memberships/034mnv495845b

The Location HTTP header provides the new URL of the membership resource. Any further manipulation of the resource will have to be done through this URL. The URL used to update this resource will no longer work, returning a 404 Not Found response.

Error situations are handled in the same manner as when updating a membership </resources/membership_create_update>.

Invalid Payload 1

The user with the specified uid already has an active membership for this station, which overlaps with the validity period of this membership. At the moment, we only allow users who have one active membership at any time period.

Input
{ 
    "uid": "c476e7f8-c053-4352-a27a-2fc0aa972f07", 
}
Output - Status code: 200
{ 
    "errors": { "__all__": [ "The UID c476e7f8-c053-4352-a27a-2fc0aa972f07 has already activated membership membership-of-john-smith-123456" ] } 
}

Invalid Payload 2

The current membership has already been activated by a user so it can’t be activated.

Input
{
    "uid": "c476e7f8-c053-4352-a27a-2fc0aa972f07",
}
Output - Status code: 409
{ 
    "errors": { "__all__": [ "The membership membership-of-john-smith-123456 was already activated with UID c476e7f8-c053-4352-a27a-2fc0aa972f07" ] } 
}

Invalid Payload 3

The uid provided does not belong to a user, as registered in the Profile Service.

Input
{ 
    "uid": "c476e7f8-c053-4352-a27a-2fc0aa972f07", 
}
Output - Status code: 400
{ 
    "errors": { "uid": [ "The given UID is not valid." ] } 
}

Invalid Payload 4 - the Profile Service is down, unreachable, or otherwise has returned an error.

Input
{ 
    "uid": "c476e7f8-c053-4352-a27a-2fc0aa972f07", 
}
Output - Status Code: 500
{ 
    "errors": { "uid": [ "We're unable to determine the validity of the UID now. Retry later." ] } 
}

HTTP Status Codes

Possible status codes returned are 200, 400, 401, 403, 404, 409, 500. httpresponsecodes

__________________________________________________________________________

Rules for reconciling two memberships with identical UIDs

This section describes the actions MVault takes when two memberships in the database share the same PBS Account profile UID. 

  • The membership that has been in existence for a longer period of time (i.e.: has an earlier start date) or has a later expiration date overrides the other...or, "wins."
  • If two memberships have identical start dates, the membership with a later expiration date wins.
  • If two memberships have varying start dates and have both started, the one with a later expiration date wins. 
  • If one membership has started but has been active for a shorter time than a membership that has existed for a longer period of time but has not yet started, the former wins. Having a LIVE membership is more valuable than one that hasn't started even if the expiration date is further in the future.

__________________________________________________________________________

Membership:on_conflict (PATCH)

Resolves the activation process for two or more memberships that share the same UID. (info) Learn how to find your station ID

Learn how MVault handles two membership records with identical UIDs

HTTP Request
PATCH https://mvault.services.pbs.org/api/{membership_id}/activate?on_conflict={value}

URI Parameters

Name
Value
Description
membership_idstringID of the membership, as supplied by the station
on_conflictstring

Specifies how overlapping memberships are handled

Values: deactivate / delete / fail

Sample request
http:/mvault.services.pbs.org/api/0100112633/activate?on_conflict=deactivate 
Sample output
{
  "grace_period": "2017-07-13T19:46:29Z",
  "update_date": "2016-04-14T19:52:11Z",
  "first_name": "Mike",
  "last_name": "Smith",
  "create_date": "2016-01-21T20:38:04Z",
  "offer": "test-mvod-offer-1",
  "notes": "",
  "current_state": {
    "explanation": {
      "status": "On",
      "timing": "within_start_expire_dates",
      "token_activated": false
    },
    "has_access": false
  },
  "membership_id": "0100112633",
  "start_date": "2016-01-21T05:00:00Z",
  "status": "On",
  "token": "common-plug-moon-vanilla",
  "additional_metadata": "{\"roi_last_change_date\":\"2016-04-14T19:52:11Z\"}",
  "activation_date": null,
  "provisional": false,
  "expire_date": "2017-04-14T19:46:29Z",
  "pbs_profile": null,
  "email": "msmith1@verizon.net"
}

Membership:delete

Delete a membership for station. (info) Learn how to find your station ID

HTTP Request
DELETE http:/mvault.services.pbs.org/api/{station_id}/memberships/{membership_id}
HTTP Request
DELETE http:/mvault.services.pbs.org/api/{station_id}/memberships/by_mvault_id/{mvault_id}/

URI Parameters

Name
Value
Description
station_idslugFlagship station ID
membership_idstringID of the membership, as supplied by the station
mvault_idstringAuto-generated unique identifier for all MVault memberships. This ID is also stored with transaction and subscription data in TVault and can be used to cross reference data between MVault and TVault for members who have made transactions that went through TVault. This field is read-only.
Sample request
http:/mvault.services.pbs.org/api/f3842586-2c40-43fa-a79f-841fd5f2b9cb/memberships/hld_55293 

Example output

You will receive a 204 NO CONTENT message but there will be no response written out.

Pagination

To prevent MVault (Passport) servers from being overloaded, automatic pagination has been implemented in the API.  Each valid request at a list endpoint results in a page displaying no more than 50 results by default.  If the number of results from a call exceeds 50, links to additional pages are available at the top of the results listing.  Each page contains data describing:

  • Current page number
  • Maximum number of objects per page
  • Number of objects on the current page
  • Total number of items
  • A link to the previous page (if one exists)
  • A link to the next page (if one exists)

You can access paginated results using URL query parameters:

  • page
    • current page number
    • defaults to 1
  • page_size
    • number of objects for current page
    • defaults to 50
    • supports a maximum value of 1000


Omitting these query parameters will always result in the first page (page 1) being returned with a page_size of 50 objects.  You must make additional calls to return subsequent pages.


Example

In the example below, we assume two things:

  1. A station with {station_id} 'f3842586-2c40-43fa-a79f-841fd5f2b9cb' has registered three memberships with ids 'foo', 'bar' and 'baz.'
  2. The maximum number of objects displayed per page is set to 2.

An authenticated call at the url http://mvault.services.pbs.org/api/f3842586-2c40-43fa-a79f-841fd5f2b9cb/memberships/?page=1&page_size=2 results in:

Page 1
{     
    "collection_info": {        
        "current_page_number": 1, 
        "total_items_count": 3, 
        "items_per_page": 2, 
        "items_current_page": 2, 
        "next_page_url": "http://mvod.pbs.org/api/ABCD/memberships/?page=2"     
    },     
     "objects": [         
	{             
	     ...             
	     "membership_id": "foo",             
	     "start_date": "2013-02-11T10:53:58",             
	     "expire_date": "2014-04-11T10:53:58",             
	     "email": "foo@provider.com",             
	     ...         
	},         
	{             
	     ...             
	     "membership_id": "bar",             
	     "start_date": "2013-02-11T10:53:58",             
	     "expire_date": "2014-04-11T10:53:58",             
	     "email": "bar@provider.com",             
	     ...         
	}     
     ] 
}

And then another authenticated call at the url http://mvault.services.pbs.org/api/f3842586-2c40-43fa-a79f-841fd5f2b9cb/memberships/?page=2 results in:

Page 2
{     
     "collection_info": {         
	"current_page_number": 2,         
	"total_items_count": 3,         
	"items_per_page": 1,         
	"items_current_page": 1,         
	"previous_page_url": "http://mvod.pbs.org/api/ABCD/memberships/?page=1"     
     },     
     "objects": [         
	{             
	     ...             
	     "membership_id": "baz",             
	     "start_date": "2013-02-11T10:53:58",             
	     "expire_date": "2014-04-11T10:53:58",             
	     "email": "baz@provider.com",             
	     ...         
	}     
     ] 
}

Return to first page

Return to the first page by using the "previous_page_url" ( http://mvault.services.pbs.org/api/f3842586-2c40-43fa-a79f-841fd5f2b9cb/memberships/?page=1 ).

Exceeding maximum pagination

If you request a page beyond the number of results returned you will receive an error message.

Bad pagination request - not enough results
{     
    "errors": "Invalid page number. Minimum is 1, maximum is 1" 
}

Additional information

This section offers addtional information that is useful for developers who may be less familiar with APIs.

Before you start

Before you begin using this API, familiarize yourself with the following:

  • The core concepts of the JSON (JavaScript Object Notation) data format. JSON is a common, language-independent data format that provides a simple text representation of arbitrary data structures. For more information, see json.org.
  • The Basic Authentication HTTP Protocol. To use the API, Basic authentication must be used. authentication.

Resources and resource types

A resource is an individual data entity with a unique identifier. The table below describes the different types of resources that you can interact with using the API.

Resource TypeDescription
Membership

Memberships represent station acknowledgements for donations.

Supported Actions

The API supports the following actions for profiles resources:

ActionDescriptionInclude valuesSupports Membership?
get

Returns a specific membership that matches both the {call_sign} and {membership_id} URL parameters.

call_sign, membership_id(tick)
list

Returns a list of memberships that match the station {call_sign} parameter. The {call_sign} parameter is a case insensitive string format containing letters only.

call_sign(tick)
create/update

Creates or updates the membership, combining both the {call_sign} and {membership_id} URL parameters.

call_sign, membership_id(tick)

Resource representation

The JSON structure below shows the format of a membership resource:

{
    "status":"On",
    "last_name":"Smith",
    "create_date":"2014-06-23T06:52:50.000000Z",
    "offer":"offer123",
    "additional_metadata":"{\"key\":\"value\"}",
    "membership_id":"QWER" ,
    "activation_date":null,
    "update_date":"2014-06-26T15:06:01.389977Z",
    "first_name":"John",
    "notes":"thisisthemembershipcreatedforJohnSmith",
    "start_date":"2013-02-11T10:53:58.000000Z",
    "expire_date":"2014-04-11T10:53:58.000000Z" ,
    "email":johnsmith@provider.com,
    "provisional":false
}

Output Values

Parameter nameValueDescriptionExample
first_namestringDonor first name.Blake
last_namestringDonor last name.Deveraux
emailemailDonor email.bdev@myemail.com
phonestringDonor 703-555-1212
offerstringThe ID of an offer, given by its creating station.WMEG Passport benefit
notesstringAdditional notes for this membership.null
grace_perioddatetime
2016-10-19T18:38:24Z
start_datedatetimeMembership start date.2016-04-21T18:38:21Z
expire_datedatetimeMembership expire date.2016-07-21T18:38:24Z
membership_idstringAn identifier for the Membership.pri01350553
create_datedatetimeThe date the Membership was created.2016-04-21T18:38:40Z
update_datedatetimeThe date the Membership was last updated.2016-04-21T18:38:40Z
activation_datedatetimeThe date the Membership was activated.2016-04-21T18:38:21Z
statusstringThe status of the membership. Values: On, Off.On
provisionalboolWhether this membership needs extra verifications.true
additional_metadatastringAdditional metadata regarding the membership.
current_statestringWhether or not the member currently has access to Passport content, based on status, timing, and token_activated.n/a
explanationbool

Provides the values for status, timing, and token_activated, which are used to determine whether or not a member currently has Passport access. 

"status": "On"
"timing": "within_start_expire_dates"
"token_activated": false

has_accessbool

Indicates whether or not the member currently has access to Passport content.

  • Is true only when all three criteria (status, timing, and token_activated) are met. This means status must be On, timing must be current/valid, and token_activated must be true.
  • Is false when any of the three criteria (status, timing, and token_activated) are not met.
false

Output format

Datetime

Datetime represents strings that are formatted to correspond to the date and time.

The datetime value parameters are output in the format described by the W3C, the version named "Complete date plus hours, minutes and seconds," with the timezone always set to UTC (http://www.w3.org/TR/NOTE-datetime). The formal description of the format is 'YYYY-MM-DDThh:mm:ssZ'.  This format includes the year, month, day of the month, hour, minute and seconds. The 'Z' at the end represents the UTC timezone.  Example:: "2013-02-11T10:53:58Z."

StringMeaning
YYYYThe year, 4 digits (eg. 2014)
MMMonth, 2 digits (01 to 12)
DDDay of the month, 2 digits (01 to 31)
hhHour, 2 digits (00 to 23)
mmMinute, 2 digits (00 to 60)
ssSeconds, 2 digits (00 to 60)
String

JSON requires a line be terminated with the double quote character (").  Strings including this character can escape it by adding a backslash (\) right before the double quote.  For example, if in the notes field we have the following text:

     He said "I like double quotes," but she said "I don't,"

This will be displayed as:

     "notes" : "He said \"I like double quotes\", but she said \"I don't\""

SlugA slug contains alphanumeric characters (lower case only) and the underscore character '_'.
BooleanBoolean values that appear in JSON as unquoted strings true or false

HTTP Response Status Codes

The possible status codes returned by this call are as follows:

Status codeDefinitionResolution
200SuccessOperation was successful.
400Bad requestDescription of the error will be given in the payload.
401Unauthenticated

consumer

The consumer with this key:secret pair doesn't exist in the

system.

403Unauthorized

consumer

The consumer with thie key:secret doesn't have access to this resource.

404No resources foundThe demanded resources can not be found.
500Internal server errorUnknown error.