Subscribers Data

This endpoint returns raw subscriber data along with the NCS-specific linking information (the NCS OccupantId, and AddressId).

The API endpoint is at:

https://{yourdomain}/appservices/api/v1/External/Data/NCS/Subscribers?startDate=2016-10-01&endDate=2016-10-02

 

Note: {yourdomain} would typically look like syncaccess-sync-demo1.syncronex.com in a production environment or syncaccess-sync-demo1.stage.syncronex.com in a test/stage environment.

Params

startDate Date-Time (YYYY-MM-DD hh:mm:ss) assumed UTC Starting date and time of the requested date range
endDate Date-Time (YYYY-MM-DD hh:mm:ss) assumed UTC Ending date and time of the requested date range
includeNeverSubscribers Boolean True to show only those users that created an account but did not purchase a plan. Default value is False
includeSubscribers Boolean False to exclude subscribers. Default value is True

The startDate and endDate parameters are optional here but omitting them can lead to extremely long download times depending on the size of your Subscriber data set.  It's recommended that you provide a start and end date in this call.  Note that the start and end dates correspond to the date and time that the user record was created within syncAccess.

Response

Http Status Code Description
404 - Not Found The endpoint will return an HTTP Status Code of 404 (Not Found) if there are no subscribers found that were created with the supplied date range.
400 - Bad Request The endpoint will return an HTTP Status Code of 400 (bad request) if the input arguments are malformed (i.e., the end date is before the start date)
200 - Ok The endpoint will respond with an HTTP Status Code of 200 (Ok) and a JSON response representing an array of Subscriber records.  
Response body is in JSON format.  Example:
 [
  {
    UserId: 0,                  // unique, immutable, identifier for the user
    Email: string,
    FirstName: string,
    LastName: string,
    PhoneNumber: string,      // unformatted raw phone number
    BillingAddress: {
      Address1: string, // Street Address
      Address2: string, // Unit information
      Address3: string, // Company Name
      Address4: string, // not used
      Address5: string, // not used
      City: string,
      State: string
      Zip: string,
      Country: string,
      Company: string
    },
    ShippingAddress: {          // see comments above
      Address1: string,
      Address2: string,
      Address3: string,
      Address4: string,
      Address5: string,
      City: string,
      State: string,
      Zip: string,
      Country: string,
      Company: string
    },
    CreatedDate:date/time,
    SubscriberType:string,
    OccupantId: string, // NCS Subscriber OccupantID
    AddressId: string         // NCS Subscriber AddressID
  }
]
UserId Int Unique, immutable, identifier for the subscriber. The UserId value is the primary key within syncAccess for the subscriber.  This can be used to associate data from other raw extracts.  The UserId is unique and can't be changed.
Email String The subscriber's email address
FirstName String Subscriber First Name
LastName String Subscriber Last Name
PhoneNumber String Unformatted, raw, phone number on record for the subscriber
BillingAddress Object
   Address1 String Billing Street Address
   Address2 String Billing Unit Designator (i.e., Suite, Apartment, floor, etc.)
   Address3 String Billing Company Name
   Address4 String Not Used
   Address5 String Not Used
   City String Billing City
   State String Billing State
   Zip String Billing Zip Code
   Country String Billing Country
   Company String Billing Company Name (duplicate of Address3 field)
Shipping Address Object
   Address1 String Shipping Street Address
   Address2 String Shipping Unit Designator (i.e., Suite, Apartment, floor, etc.)
   Address3 String Shipping Company Name
   Address4 String Not Used
   Address5 String Not Used
   City  String Shipping City
   State String Shipping State
   Zip String Shipping Zip Code
   Country String Shipping Country
   Company String Shipping Company Name (duplicate of Address3 field)
CreatedDate Date-time (UTC) Date and Time that the record was created in syncAccess. Format is YYYY-MM-DDTHH:MM:SS.FF
SubscriberType String Value of "New Sub" means the user was created via new start through syncAccess.
Value of "Existing" means the user activated an already-existing print subscription account.
OccupantId String The NCS-specific Occupant Identifier linked to the syncAccess Account
AddressId String The NCS-specific Address Identifier linked to the syncAccess Account

Non-Subscriber Data

It’s possible to use the Subscribers data extract to fetch non-subscriber data. Specifically, those users that created accounts in the system but never went on to purchase any plans.  These are sometimes referred to as Registered-Only users.  

Use the input parameters includeNeverSubscribers and includeSubscribers to get a list of only those users that have never purchased a plan.  For example:

https://{yourdomain}/appservices/api/v1/External/Data/NCS/Subscribers?startDate=2016-10-01&endDate=201610-02&includeNeverSubscribers=true&includeSubscribers=false

Note that users that have not purchased a plan will only have  a minimal amount of profile data in the system.  You can expect to see: email address, userId in the result data.  You might also get FirstName, LastName, and PhoneNumber in your results. Address Information and Circulation System information (i.e., OccupantId, AddressId) will be null/empty for these users.