--- title: "Membership Vault API" canonical: "https://docs.pbs.org/space/MV/5799969/Membership%20Vault%20API" format: markdown --- # Introduction The MVault API is a programming interface designed to integrate your app with [Passport](https://docs.pbs.org/space/PLUS/5505086/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. # 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](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. > ℹ️ 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/](http://www.base64encode.org/) to encode it. ### How do I obtain authentication credentials? To obtain authentication credentials please [submit a support ticket](http://digitalsupport.pbs.org/support/tickets/new).  # Date and Time All date time fields are represented in [UTC format](https://en.wikipedia.org/wiki/Coordinated_Universal_Time). 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](https://docs.pbs.org/display/uua) ('user id' - also known as PBS Account ID). To do this, use the PATCH endpoint described here:  - [Membership:update (PATCH)](https://docs.pbs.org/space/MV/5799969/Membership+Vault+API#Update-the-membership-ID-for-a-Membership-(PATCH))  by membership_id - [Membership:update (PATCH)](https://docs.pbs.org/space/MV/5799969/Membership+Vault+API#Membership:on_conflict-(PATCH))  by mvault_id # Endpoints - [Membership:put](https://docs.pbs.org/space/MV/5799969/Membership+Vault+API#Membership:put) - [Membership:get](https://docs.pbs.org/space/MV/5799969/Membership+Vault+API#Membership:get) - [Membership:deleted](https://docs.pbs.org/space/MV/5799969/Membership+Vault+API#Membership:deleted) - [Membership:deleted?since](https://docs.pbs.org/space/MV/5799969/Membership+Vault+API#Membership:deleted?since) - [Membership:list](https://docs.pbs.org/space/MV/5799969/Membership+Vault+API#Membership:list) - [Memberships:last_updated_since](https://docs.pbs.org/space/MV/5799969/Membership+Vault+API#Memberships/?last_updated_since) - [Memberships:active?](https://docs.pbs.org/space/MV/5799969/Membership+Vault+API#Memberships:active?) - [Memberships:email](https://docs.pbs.org/space/MV/5799969/Membership+Vault+API#Memberships:station/email) - [Membership:list_activated](https://docs.pbs.org/space/MV/5799969/Membership+Vault+API#Membership:list_activated) - [Membership:list_activated/?since](https://docs.pbs.org/space/MV/5799969/Membership+Vault+API#Membership:list_activated/?since) - [Membership:list_activated/?exclude_profile_data](https://docs.pbs.org/space/MV/5799969/Membership+Vault+API#Membership:list_activated/?exclude_profile_data) - [Membership:list_provisional](https://docs.pbs.org/space/MV/5799969/Membership+Vault+API#Membership:list_provisional) - [Membership:list_provisional/?since](https://docs.pbs.org/space/MV/5799969/Membership+Vault+API#Membership:list_provisional/?since) - [Membership:list_grace_period](https://docs.pbs.org/space/MV/5799969/Membership+Vault+API#Membership:list_grace_period) - [Membership:list_token](https://docs.pbs.org/space/MV/5799969/Membership+Vault+API#Membership:list_token) - [Membership:list_uid](https://docs.pbs.org/space/MV/5799969/Membership+Vault+API#Membership:list_uid) - [Membership:update](https://docs.pbs.org/space/MV/5799969/Membership+Vault+API#Membership:update) - [Membership:update (PATCH)](https://docs.pbs.org/space/MV/5799969/Membership+Vault+API#Update--the-membership-ID-for-a--Membership-(PATCH)) - [Membership:on_conflict (PATCH)](https://docs.pbs.org/space/MV/5799969/Membership+Vault+API#Membership:on_conflict-(PATCH)) - [Membership:delete](https://docs.pbs.org/space/MV/5799969/Membership+Vault+API#Membership:delete) - [Output values](https://docs.pbs.org/space/MV/5799969/Membership+Vault+API#Output-Values) > ❌ **If your API client does not support any of the following HTTP methods, you may use the X-HTTP-Method-Override header. ****[Learn more](http://www.hanselman.com/blog/HTTPPUTOrDELETENotAllowedUseXHTTPMethodOverrideForYourRESTServiceWithASPNETWebAPI.aspx)**** ** ##### **Base Endpoint** ``` https://mvault.services.pbs.org/api/ ``` ## > Macro (anchor) 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. 🙂 ### Create a Membership  This section describes the payload format required to create a Membership. :info: **[Learn how to find your station ID](https://pbs-docs.atlassian.net/wiki/spaces/MV/pages/5799994)** ##### **HTTP Request** ``` PUT https://mvault.services.pbs.org/api/{station_id}/memberships/{membership_id}/ ``` ### URI Parameters | **Parameter name ** | **Value ** | **Description ** | | --- | --- | --- | | station_id | slug | Flagship station ID | | membership_id | string | ID of the membership, as supplied by the station | | mvault_id | string | Auto-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](https://docs.pbs.org/space/MV/5799969/Membership+Vault+API#HTTP-Response-Status-Codes) 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. :check_mark: = True    :cross_mark: = False | **Parameter name** | **Mandatory** | **Optional** | **Read-Only** | **Has default** | **Default value** | | --- | --- | --- | --- | --- | --- | | first_name | :check_mark: | :cross_mark: | :cross_mark: | :cross_mark: | | | last_name | :check_mark: | :cross_mark: | :cross_mark: | :cross_mark: | | | email | :cross_mark: | :check_mark: | :cross_mark: | :cross_mark: | | | offer | :check_mark: | :cross_mark: | :cross_mark: | :cross_mark: | | | notes | :cross_mark: | :check_mark: | :cross_mark: | :cross_mark: | | | start_date | :check_mark: | :cross_mark: | :cross_mark: | :cross_mark: | | | expire_date | :check_mark: | :cross_mark: | :cross_mark: | :cross_mark: | | | create_date | :cross_mark: | :cross_mark: | :check_mark: | :cross_mark: | | | update_date | :cross_mark: | :cross_mark: | :check_mark: | :cross_mark: | | | activation_date | :cross_mark: | :cross_mark: | :check_mark: | :cross_mark: | | | membership_id | :cross_mark: | :cross_mark: | :check_mark: | :cross_mark: | | | pbs_profile | :cross_mark: | :cross_mark: | :check_mark: | :cross_mark: | | | status | :cross_mark: | :check_mark: | :cross_mark: | :check_mark: | On | | provisional | :cross_mark: | :check_mark: | :cross_mark: | :check_mark: | false | | additional_metadata | :cross_mark: | :check_mark: | :cross_mark: | :cross_mark: | | | token | :cross_mark: | :cross_mark: | :check_mark: | :cross_mark: | | ## > Macro (anchor) 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](https://pbs-docs.atlassian.net/wiki/spaces/MV/pages/5799994)** ##### **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](https://pbs-docs.atlassian.net/wiki/spaces/MV/pages/5799994)** ##### **HTTP Request** ``` GET https://mvault.services.pbs.org/api/{station_id}/memberships/by_mvault_id/{mvault_id}/ ``` ### URI Parameters | **Name** | **Value** | **Description** | | --- | --- | --- | | station_id | slug | Flagship station ID | | membership_id | string | ID of the membership, as supplied by the station | | mvault_id | string | Auto-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](https://docs.pbs.org/space/MV/5799969/Membership+Vault+API#HTTP-Response-Status-Codes) _________________________________________________________________________________ ## > Macro (anchor) Membership:deleted Returns a list of all deleted memberships for a specific station ID. :info: **[Learn how to find your station ID](https://pbs-docs.atlassian.net/wiki/spaces/MV/pages/5799994)** ### HTTP Request ``` GET https://mvault.services.pbs.org/api/{station_id}/memberships/filter/deleted ``` ### URI Parameters | **Parameter Name** | **Value** | **Description** | | --- | --- | --- | | station_id | slug | Flagship station ID | ### Example Output This endpoint can be filtered by [pagination](https://docs.pbs.org/space/MV/5799969/Membership+Vault+API#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" } ] ``` _________________________________________________________________________________ ## > Macro (anchor) 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](https://pbs-docs.atlassian.net/wiki/spaces/MV/pages/5799994)** ### **HTTP Request** ``` GET http://mvault.services.pbs.org/api/{station_id}/memberships/filter/deleted?since=2015-06-07T00:00:00Z ``` ### URI Parameters | **Parameter Name** | **Value** | **Description** | | --- | --- | --- | | station_id | slug | Flagship station ID | ### Query Parameters | **Parameter Name** | **Value** | **Description** | | --- | --- | --- | | Membership Vault API#last-updated-since | datetime | 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 *Membership Vault API#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" } ] } ``` _________________________________________________________________________________ ## > Macro (anchor) Membership:list Returns a list of all members associated with a specific station ID. :info: **[Learn how to find your station ID](https://pbs-docs.atlassian.net/wiki/spaces/MV/pages/5799994)** ### **HTTP Request** ``` GET https://mvault.services.pbs.org/api/{station_id}/memberships/ ``` ### URI Parameters | **Parameter Name** | **Value** | **Description** | | --- | --- | --- | | station_id | slug | Flagship station ID | ### Query Parameters | **Parameter Name** | **Value** | **Description** | | --- | --- | --- | | Membership Vault API#last-updated-since | datetime | 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 *Membership Vault API#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" } ] } ``` ### > Macro (anchor) 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](https://pbs-docs.atlassian.net/wiki/spaces/MV/pages/5799994)** ##### **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.  [View HTTP Status Codes](https://docs.pbs.org/space/MV/5799969/Membership+Vault+API#HTTP-Response-Status-Codes) ### > Macro (anchor) 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](https://pbs-docs.atlassian.net/wiki/spaces/MV/pages/5799994)** (2) By time-based windowing using start_date and end_date params.  :info:** ****[Learn how email is validated](https://docs.djangoproject.com/en/1.10/_modules/django/core/validators/#EmailValidator)** ### URI Parameters | **Parameter Name** | **Value** | **Description** | **Required?** | | --- | --- | --- | --- | | station_id | string | Flagship station ID | Y | | email address | string | Email address of the member | N | | start_date, end_date | datetime | 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" }  ``` _____________________________________________________________________________ ### > Macro (anchor) 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](https://pbs-docs.atlassian.net/wiki/spaces/MV/pages/5799994)** :info:** ****[Learn how email is validated](https://docs.djangoproject.com/en/1.10/_modules/django/core/validators/#EmailValidator)** ### URI Parameters | **Parameter Name** | **Value** | **Description** | | --- | --- | --- | | station_id | string | Flagship station ID | | email address | string | Email 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" } ] } ``` _____________________________________________________________________________ ## > Macro (anchor) Membership:list_activated Returns a list of all activated members associated with a specific station ID.  :info: **[Learn how to find your station ID](https://pbs-docs.atlassian.net/wiki/spaces/MV/pages/5799994)** ##### **HTTP Request** ``` GET https://mvault.services.pbs.org/api/{station_id}/memberships/filter/activated/ ``` ### URI Parameters | **Parameter Name** | **Value** | **Description** | | --- | --- | --- | | station_id | slug | Flagship station ID | ### Query Parameters | **Parameter Name** | **Value** | **Description** | | --- | --- | --- | | [since](https://docs.pbs.org/space/MV/5799969/Membership+Vault+API#Membership:list_activated/?since) | datetime | 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](https://docs.pbs.org/space/MV/5799969/Membership+Vault+API#Paginate.1) | integer | Show the results on a specific page. See the [Membership Vault API#Pagination](https://pbs-docs.atlassian.net/wiki/pages/resumedraft.action?draftId=5799969#MembershipVaultAPI-Pagination) section for more details. | | [page_size](https://docs.pbs.org/space/MV/5799969/Membership+Vault+API#Paginate.1) | integer | Specify number of objects for current page. See the [Membership Vault API#Pagination](https://pbs-docs.atlassian.net/wiki/pages/resumedraft.action?draftId=5799969#MembershipVaultAPI-Pagination) section for more details. | | [exclude_profile_data](https://docs.pbs.org/space/MV/5799969/Membership+Vault+API#Membership:list_activated/?exclude_profile_data) | integer | Exclude PBS profile user data eliminating external calls towards profile-service API | ### Example Output The response for a request made to this endpoint will be [Membership Vault API#pagination](https://docs.pbs.org/space/MV/5799969/Membership+Vault+API#Paginate.1). ##### **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" } ] } ``` ### > Macro (anchor) 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](https://pbs-docs.atlassian.net/wiki/spaces/MV/pages/5799994)** ##### **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" } ] } ``` ### > Macro (anchor) 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" } ] } ``` ### > Macro (anchor) 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. [View HTTP Status Codes](https://docs.pbs.org/space/MV/5799969/Membership+Vault+API#HTTP-Response-Status-Codes) _______________________________________________________________________________ ## > Macro (anchor) 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](https://pbs-docs.atlassian.net/wiki/spaces/MV/pages/5799994)** ##### **HTTP Request** ``` GET https://mvault.services.pbs.org/api/{station_id}/memberships/filter/provisional/ ``` ### URI Parameters | **Parameter Name** | **Value** | **Description** | | --- | --- | --- | | station_id | slug | Flagship station ID | ### Query Parameters | **Parameter Name** | **Value** | **Description** | | --- | --- | --- | | since | datetime | Filter the result, showing only the provisional memberships, created after the date specified here. | | page | integer | Show the results on a specific page. See the [Membership Vault API#pagination](https://pbs-docs.atlassian.net/wiki/pages/resumedraft.action?draftId=5799969#MembershipVaultAPI-pagination) section for more details. | ### Example Output The response for a request made to this endpoint will be [paginated](https://docs.pbs.org/space/MV/5799969/Membership+Vault+API#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": ""         },     ] }  ``` ### > Macro (anchor) 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](https://pbs-docs.atlassian.net/wiki/spaces/MV/pages/5799994)** ##### **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" } ] }   ``` ### > Macro (anchor) 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. [View HTTP Status Codes](https://docs.pbs.org/space/MV/5799969/Membership+Vault+API#HTTP-Response-Status-Codes) _________________________________________________________________________________ ## > Macro (anchor) 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](https://pbs-docs.atlassian.net/wiki/spaces/MV/pages/5799994)** 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 name** | **Value** | **Description** | | --- | --- | --- | | station_id | slug | Flagship station ID | ### Example Output The response for a request made to this endpoint will be [paginated](https://docs.pbs.org/space/MV/5799969/Membership+Vault+API#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" } ] }  ``` _________________________________________________________________________________ ## > Macro (anchor) Membership:list_token Search for users by token for a particular station. :info: **[Learn how to find your station ID](https://pbs-docs.atlassian.net/wiki/spaces/MV/pages/5799994)** ##### **HTTP Request** ``` GET https://mvault.services.pbs.org/api/{station_id}/memberships/filter/token/{token}/ ``` ### URI Parameters | **Parameter name** | **Value** | **Description** | | --- | --- | --- | | station_id | slug | Flagship station ID | | token | string | User's activation token | ### Example Output The response for a request made to this endpoint will be [Membership Vault API#pagination](https://pbs-docs.atlassian.net/wiki/pages/resumedraft.action?draftId=5799969#MembershipVaultAPI-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" } ``` _________________________________________________________________________________ ## > Macro (anchor) Membership:list_uid Search for users by UID for a particular station. :info: **[Learn how to find your station ID](https://pbs-docs.atlassian.net/wiki/spaces/MV/pages/5799994)** ##### **HTTP Request** ``` GET https://mvault.services.pbs.org/api/{station_id}/memberships/filter/uid/{uid}/ ``` ### URI Parameters | **Parameter name** | **Value** | **Description** | | --- | --- | --- | | station_id | slug | Flagship station ID | | uid | guid | User profile ID | ### Example Output The response for a request made to this endpoint will be [paginated](https://docs.pbs.org/display/MV/Membership+Vault+API#MembershipVaultAPI-Pagination). ``` [ { "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" } ] ``` _________________________________________________________________________________ ## > Macro (anchor) Membership:update The Membership:update endpoint has two different functions: 1. [Create](https://docs.pbs.org/space/MV/5799969#Create-a-Membership) - Create an entirely new membership record or make edits to an existing membership record. 2. [Update](https://docs.pbs.org/space/MV/5799969#Update.1) - Change the membership ID while leaving rest of record unchanged. ### > Macro (anchor) Edit a Membership  This section describes the payload format required to edit a Membership. :info: **[Learn how to find your station ID](https://pbs-docs.atlassian.net/wiki/spaces/MV/pages/5799994)** ##### **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_id | slug | Flagship station ID | | membership_id | string | ID of the membership, as supplied by the station | | mvault_id | string | Auto-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 [HTTP response status code](https://docs.pbs.org/space/MV/5799969/Membership+Vault+API#HTTP-Response-Status-Codes) is 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. :check_mark: = True    :cross_mark: = False | **Parameter name** | **Mandatory** | **Optional** | **Read-Only** | **Has default** | **Default value** | | --- | --- | --- | --- | --- | --- | | first_name | :check_mark: | :cross_mark: | :cross_mark: | :cross_mark: | | | last_name | :check_mark: | :cross_mark: | :cross_mark: | :cross_mark: | | | email | :cross_mark: | :check_mark: | :cross_mark: | :cross_mark: | | | offer | :check_mark: | :cross_mark: | :cross_mark: | :cross_mark: | | | notes | :cross_mark: | :check_mark: | :cross_mark: | :cross_mark: | | | start_date | :check_mark: | :cross_mark: | :cross_mark: | :cross_mark: | | | expire_date | :check_mark: | :cross_mark: | :cross_mark: | :cross_mark: | | | create_date | :cross_mark: | :cross_mark: | :check_mark: | :cross_mark: | | | update_date | :cross_mark: | :cross_mark: | :check_mark: | :cross_mark: | | | activation_date | :cross_mark: | :cross_mark: | :check_mark: | :cross_mark: | | | membership_id | :cross_mark: | :cross_mark: | :check_mark: | :cross_mark: | | | pbs_profile | :cross_mark: | :cross_mark: | :check_mark: | :cross_mark: | | | status | :cross_mark: | :check_mark: | :cross_mark: | :check_mark: | On | | provisional | :cross_mark: | :check_mark: | :cross_mark: | :check_mark: | false | | additional_metadata | :cross_mark: | :check_mark: | :cross_mark: | :cross_mark: | | | token | :cross_mark: | :cross_mark: | :check_mark: | :cross_mark: | | > ⚠️ **There currently is no API to support retrieval of offer IDs.** ### Update Update (edit) differs slightly from [Create](https://docs.pbs.org/space/MV/5799969/Membership+Vault+API#Create-a-Membership), 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. [View HTTP Status Codes](https://docs.pbs.org/space/MV/5799969/Membership+Vault+API#HTTP-Response-Status-Codes) > Macro (anchor)  _________________________________________________________________________________   ## > Macro (anchor) Update the membership ID for a Membership (PATCH) This section describes the payload format required to update the membership ID for a[ ](https://docs.pbs.org/membership.html)*Membership*. While this call is primarily for updating the membership ID, other fields can be updated using this call as well.  **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](https://docs.pbs.org/space/MV/5799969/Membership+Vault+API#Membership:get). :info: **[Learn how to find your station ID](https://pbs-docs.atlassian.net/wiki/spaces/MV/pages/5799994)** [Learn how MVault handles two membership records with identical UIDs](https://docs.pbs.org/space/MV/5799969/Membership+Vault+API#Membership:on_conflict-(PATCH))
View PATCH steps The following example is executed using the Google Postman app. - Check the Membership ID in the [MVault console](https://mvault.console.pbs.org/) (Figure 1). Figure 1  ![image](media://f3d7d4b9-6e4b-426c-9f15-b1fb3879bc4d) - Type the** full URL with the existing membership_id** (Figure 2.1). - Example: * **[https://mvault.services.pbs.org/api/f3842586-2c40-43fa-a79f-841fd5f2b9cb/memberships/birthday](https://mvault.services.pbs.org/api/wkrp/memberships/birthday)** * - Make sure a "Content-Type" Header is included with the value of "application/json" - In the raw JSON field, type the **new membership_id** (Figure 2.2). - Example:  *{ "membership_id" : "easter" }* - Click **Send** (Figure 2.3). Figure 2  ![image](media://acaef658-4cf7-4ab7-8a11-9ac18f773fda) - If the call executed successfully, the Status displays 200 OK.  The time it took to process is also displayed (Figure 3). Figure 3  ![image](media://6994c0eb-41de-424e-9a97-abb51c75ae28) - Check the new Membership ID in the [MVault console](https://mvault.console.pbs.org/) (Figure 4). Figure 4  ![image](media://9f395271-c4bd-4fa9-a3b8-f85b560be028)
##### **TTP Request** ``` PATCH https://mvault.services.pbs.org/api/{station_id}/memberships/{membership_id}/ ``` ## URI Parameters | **Parameter name ** | **Value ** | **Description ** | | --- | --- | --- | | station_id | slug | Flagship station ID | | membership_id | string | ID of the membership, as supplied by the station | | mvault_id | string | Auto-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 ** | **Example** | | --- | --- | | first_name | James | | last_name | Taylor | | membership_id | 0110376681 | | uid | 5d17d213-b807-4c0c-b646-478ec3615625 | | email | jtaylor@pbs.org | | phone | 703-555-1212 | | status | on | | provisional | no | | offer | Passport | | additional_metadata | | | start_date | 2019-04-15 01:00:00 (YYYY-MM-DDTHH:MM:SSZ) | | expire_date | 2019-04-15 01:00:00 (YYYY-MM-DDTHH:MM:SSZ) | 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](https://docs.pbs.org/space/MV/5799969/Membership+Vault+API#Membership:get). ##### **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 . #### 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. [View HTTP Status Codes](https://docs.pbs.org/space/MV/5799969/Membership+Vault+API#HTTP-Response-Status-Codes) __________________________________________________________________________ ## > Macro (anchor) 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. __________________________________________________________________________ ## > Macro (anchor) 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](https://pbs-docs.atlassian.net/wiki/spaces/MV/pages/5799994)** [Learn how MVault handles two membership records with identical UIDs](https://docs.pbs.org/space/MV/5799969#Rules-for-reconciling-two-memberships-with-identical-UIDs) ##### **HTTP Request** ``` PATCH https://mvault.services.pbs.org/api/{membership_id}/activate?on_conflict={value} ``` ### URI Parameters | **Name** | **Value** | **Description** | | --- | --- | --- | | membership_id | string | ID of the membership, as supplied by the station | | on_conflict | string | 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" } ``` ## > Macro (anchor) Membership:delete Delete a membership for station. :info: **[Learn how to find your station ID](https://pbs-docs.atlassian.net/wiki/spaces/MV/pages/5799994)** ##### **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_id | slug | Flagship station ID | | membership_id | string | ID of the membership, as supplied by the station | | mvault_id | string | Auto-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](http://mvault.services.pbs.org/api/ABCD/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 additional 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](http://json.org/). - **The Basic Authentication HTTP Protocol.** To use the API, [Basic authentication](https://docs.pbs.org/space/MV/5799969#Authentication) must be used. ## 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 Type** | **Description** | | --- | --- | | Membership | Memberships represent station acknowledgements for donations. | ## Supported Actions The API supports the following actions for profiles resources: | **Action** | **Description** | **Include values** | **Supports Membership?** | | --- | --- | --- | --- | | get | Returns a specific membership that matches both the {call_sign} and {membership_id} URL parameters. | call_sign, membership_id | :check_mark: | | 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 | :check_mark: | | create/update | Creates or updates the membership, combining both the {call_sign} and {membership_id} URL parameters. | call_sign, membership_id | :check_mark: | ## Resource representation The JSON structure below shows the format of a membership resource: ```python { "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 } ``` ## > Macro (anchor) Output Values | **Parameter name** | **Value** | **Description** | **Example** | | --- | --- | --- | --- | | first_name | string | Donor first name. | Blake | | last_name | string | Donor last name. | Deveraux | | email | email | Donor email. | bdev@myemail.com | | phone | string | Donor | 703-555-1212 | | offer | string | The ID of an offer, given by its creating station. | WMEG Passport benefit | | notes | string | Additional notes for this membership. | null | | grace_period | datetime | | 2016-10-19T18:38:24Z | | start_date | datetime | Membership start date. | 2016-04-21T18:38:21Z | | expire_date | datetime | Membership expire date. | 2016-07-21T18:38:24Z | | membership_id | string | An identifier for the Membership. | pri01350553 | | create_date | datetime | The date the Membership was created. | 2016-04-21T18:38:40Z | | update_date | datetime | The date the Membership was last updated. | 2016-04-21T18:38:40Z | | activation_date | datetime | The date the Membership was activated. | 2016-04-21T18:38:21Z | | status | string | The status of the membership. Values: On, Off. | On | | provisional | bool | Whether this membership needs extra verifications. | true | | additional_metadata | string | Additional metadata regarding the membership. | | | current_state | string | Whether or not the member currently has access to Passport content, based on status, timing, and token_activated. | n/a | | explanation | bool | 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_access | bool | 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](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." | **String** | **Meaning** | | --- | --- | | YYYY | The year, 4 digits (eg. 2014) | | MM | Month, 2 digits (01 to 12) | | DD | Day of the month, 2 digits (01 to 31) | | hh | Hour, 2 digits (00 to 23) | | mm | Minute, 2 digits (00 to 60) | | ss | Seconds, 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\""* | | --- | --- | | **Slug** | A slug contains alphanumeric characters (lower case only) and the underscore character '_'. | | **Boolean** | Boolean 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 code** | **Definition** | **Resolution** | | --- | --- | --- | | 200 | Success | Operation was successful. | | 400 | Bad request | Description of the error will be given in the payload. | | 401 | Unauthenticated
consumer | The consumer with this key:secret pair doesn't exist in the
system. | | 403 | Unauthorized
consumer | The consumer with thie key:secret doesn't have access to this resource. | | 404 | No resources found | The demanded resources can not be found. | | 500 | Internal server error | Unknown error. |