Users

Following, we have all information related to users management, like creating or editing an user, and many others operations.

Login / Logout

First, we describe how to an user login your instance

method: POST
URL: /sessions.json

PARAMETERS:
If Regular User:
{
  "session": {
    "login": "EMAIL",
    "password": "PASSWORD"
  }
}
If Facebook User:
{
  "session": {
    "access_token": "FACEBOOK TOKEN | FIREBASE TOKEN"
    "provider": "facebook|google"
  }
}
RETURN:
{
  "status": true/false, # status_code 200/401
  "message": "ERROR MESSAGE" # If "status" = false
}

Logout

method: POST
URL: /signout.json

New Regular User

Next, you can follow 3 steps to create a new user:

1) Request Form (with possible Custom Fields)

method: GET
URL: /management/users/new.json

PARAMETERS:
RETURN:
{
  "user": {
    "id": null,
    "name": null,
    "email": null,
    "language": "LANGUAGE", # "en","pt","es"
    "properties": [ # If exist custom fields
      {
        "id": null,
        "custom_field_id": ID,
        "value": null
      }
    ]
  },
  "custom_fields": [ # If exist custom fields
    {
      "id": ID,
      "name": "NAME",
      "field_name": {
        "en": "FIELD NAME IN ENGLISH",
        "pt": "FIELD NAME IN PORTUGUESE"
      },
      "field_type": "FIELD TYPE", # "text_box","date_picker","check_box","radio_button","combo_box"
      "field_values": [ # If "field_type" = "check_box","radio_button","combo_box"
        {
          "en": "OPTION VALUE IN ENGLISH",
          "pt": "OPTION VALUE IN PORTUGUESE",
          “parent_value”: “PARENT'S VALUE POSITION”
        }
      ],
      "required": true/false,
      "model_name": "User",
      “parent_id”: ID # Parent's ID
    }
  ]
}

2) Submit Form (with possible Custom Fields) # Show terms

method: POST
URL: /management/users.json

PARAMETERS:
{
  "user": {
    "name": "NAME",
    "email": "EMAIL",
    "email_confirmation": "EMAIL",
    "password": "PASSWORD",
    "password_confirmation": "PASSWORD",
    "permission": "user",
    "language": "LANGUAGE", # "en","pt","es"
    "user_file": "IMAGE",
    "properties_attributes": { # If exist custom fields
      "INDEX": { # 0,1,2,...
        "custom_field_id": "ID"
        "value": "POSITION", # "check_box" = “” or “|1|” or "|1||2|" or ..., "radio_button","combo_box" = "1" or "2" or ..., "date_picker" = "yyyy-mm-dd"
      }
    }
  }
}
RETURN:
{
  "status": true/false, # status_code 200/400
  "errors": { # caso "status" = false
    "user": {
      "FIELD": [ # "name","email","password","properties.value"
        "ERROR MESSAGE"
      ],
      "properties": [ # If exist custom fields
        {
          "custom_field_id": ID,
          "errors": {
            "value": [
              "ERROR MESSAGE"
            ]
          }
        }
      ]
    }
  }
}

3) Email verification

method: PUT
URL: /email_verifies/ID.json # ID = 4 digit code sent by email

PARAMETERS:
{
  "user": {
    "password": "PASSWORD",
  }
}
RETURN:
{
  "status": true/false, # status_code 200/400,401
  "error": "ERROR MESSAGE" # If "status" = false
}
Facebook User

EITV CLoud allows using Facebook as a source for user information sharing, like name and email. Using this feature a instance can create and login users using their Facebook credentials, with no password need for EiTV Cloud.

Following, we have all documentation for integration.

First, we check if there are an user with a given Facebook Token and check if Custom Fields are enabled

method: GET
URL: /sessions/new.json

PARAMETERS:
{
  "access_token": "FACEBOOK TOKEN | FIREBASE TOKEN"
  "provider": "facebook|google"
}
RETURN:
{
  "user":true/false,
  "custom_fields":true/false
}

Create New User if Custom Fields are disabled

method: POST
URL: /sessions.json

PARAMETERS:
{
  "session": {
    "access_token": "FACEBOOK TOKEN | FIREBASE TOKEN"
    "provider": "facebook|google"
  }
}
RETURN:
{
  "status": true/false, # status_code 200/401
  "message": "ERROR MESSAGE" # If "status" = false
}
New Facebook User with Custom Fields

1) Request a form with Custom Fields

method: GET
URL: /management/users/new.json

PARAMETERS:
RETURN:
{
  "user": {
    "id": null,
    "name": null,
    "email": null,
    "language": "LANGUAGE", # "en","pt","es"
    "properties": [ # Custom Fileds
        {
          "id": null,
          "custom_field_id": ID,
          "value": null
        }
    ]
  },
  "custom_fields": [ # Custom Fileds
    {
      "id": ID,
      "name": "NOME",
      "field_name": {
        "en": "FIELD NAME IN ENGLISH",
        "pt": "FIELD NAME IN PORTUGUESE"
      },
      "field_type": "FIELD TYPE", # "text_box","date_picker","check_box","radio_button","combo_box"
      "field_values": [ # If "field_type" = "check_box","radio_button","combo_box"
        {
          "en": "OPTION VALUE IN ENGLISH",
          "pt": "OPTION VALUE IN PORTUGUESE",
          “parent_value”: “PARENT'S VALUE POSITION”
        }
      ],
      "required": true/false,
      "model_name": "User",
      “parent_id”: ID # Parent's ID
    }
  ]
}

2) Submit a form with Custom Fields

method: POST
URL: /management/users.json

PARAMETERS:
{
  "user": { # não enviar "name","email","email_confirmation","password","password_confirmation"
    "access_token": "FACEBOOK TOKEN | FIREBASE TOKEN"
    "provider": "facebook|google"
    "permission": "user",
    "language": "LANGUAGE", # "en","pt","es"
    "properties_attributes": { # Custom fields
      "INDEX": { # 0,1,2,...
        "custom_field_id": "ID"
        "value": "POSITION", # "check_box" = “” or “|1|” or "|1||2|" or ..., "radio_button","combo_box" = "1" or "2" or ..., "date_picker" = "yyyy-mm-dd"
      }
    }
  }
}
RETURN:
{
  "status": true/false, # status_code 200/400
  "errors": { # if "status" = false
    "user": {
      "FIELD": [ # "name","properties.value"
        "ERROR MESSAGE"
      ],
      "properties": [ # Custom fields
        {
          "custom_field_id": ID,
          "errors": {
            "value": [
              "ERROR MESSAGE"
            ]
          }
        }
      ]
    }
  }
}
User Info

Getting User information:

method: GET
URL: /management/users/info.json

PARAMETERS:
RETURN:
{
  "page": "user",
  "user": {
    "id": ”ID", # Format: NUMBER-TEXT
    "name": "NAME",
    "email": "EMAIL",
    "language": "LANGUAGE", # "en","pt","es"
    "thumb_url": "URL",
    "facebook": true/false,
    "permission": "PERMISSION", # "admin", "publisher", "contributor", "user"
    "payment_card_last_4_digits": "NUMBER",
    "email_unsubscribed": true/false,
    "properties":[ # Custom fields
      {
        "id": ID,
        "custom_field_id": ID,
        "value": "POSITION"
      }
    ]
  },
  “channels” : [ # Subscribed channels 
    {
      “CHANNEL ID”
    }
  ],
  # if achievement_enabled (info.json)
  "achievements": [
    {
      "id": ”ID", # Format: NUMBER-TEXT
      "name": "NAME",
      "description": "DESCRIPTION",
      "html_description": "HTML ADDITIONAL DESCRIPTION",
      "points": NUMBER,
      "type": "achievement",
      "properties":[ # Custom fields
        {
          "id": ID,
          "custom_field_id": ID,
          "value": "POSITION"
        }
      ]
    }
  ],
  achievements_blocked: [
    ACHIEVEMENT_INFO
  ]
  "achievement_points": NUMBER,
  "achievement_rank": NUMBER
}

Following, we show how to get the user image:

URL: /users/[ID]/retrieve?format=thumb
ID: format NUMBER-TEXT

the achievement thumbnail:

URL: /achievements/[ID]/retrieve?format=thumb
ID: format NUMBER-TEXT

and the user achievement certificate:

URL: /users/[USER_ID]/achievements/[ACHIEVEMENT_ID].pdf
USER_ID: format NUMBER-TEXT
ACHIEVEMENT_ID: format NUMBER-TEXT

Edit User

1) Request Form (with possible custom fields)

method: GET
URL: /management/users/ID/edit.json # User ID on /management/users/info.json

PARAMETERS:
RETURN:
{
  "user": {
    "id": "ID",
    "name": "NAME",
    "email": "EMAIL",
    "language": "LANGUAGE", # "en","pt","es"
    "user_file": "IMAGE", 
    "email_unsubscribed": true/false,
    "properties": [ # If exist custom fields
      {
        "id": "ID", # ID = null, if new custom field
        "custom_field_id": ID,
        "value": "VALUE"
      }
    ]
  },
  "custom_fields": [ # If exist custom fields
    {
      "id": ID,
      "name": "NAME",
      "field_name": {
        "en": "FIELD NAME IN ENGLISH",
        "pt": "FIELD NAME IN PORTUGUESE"
      },
      "field_type": "FIELD TYPE", # "text_box","date_picker","check_box","radio_button","combo_box"
      "field_values": [ # If "field_type" = "check_box","radio_button","combo_box"
        {
          "en": "OPTION VALUE IN ENGLISH",
          "pt": "OPTION VALUE IN PORTUGUESE",
          “parent_value”: “PARENT'S VALUE POSITION”
        }
      ],
      "required": true/false,
      "model_name": "User",
      “parent_id”: ID # PARENT'S ID
    }
  ]
}

2) Submit Form (with possible custom fields)

method: PUT
URL: /management/users/ID.json

PARAMETERS:
{
  "user": {
    "name": "NAME",
    "email": "EMAIL", # If regular user
    "email_confirmation": "EMAIL", # If regular user
    "password": "PASSWORD", # If regular user and changing password
    "password_confirmation": "PASSWORD", # If regular user and changing password
    "permission": "user",
    "language": "LANGUAGE", # "en","pt","es"
    "properties_attributes": { # If exist custom fields
      "INDEX": { # 0,1,2,...
        "id": "ID" # If NOT a new custom field
        "custom_field_id": "ID"
        "value": "POSITION", # "check_box" = “” or “|1|” or "|1||2|" or ..., "radio_button","combo_box" = "1" or "2" or ..., "date_picker" = "yyyy-mm-dd"
      }
    }
  }
}
RETURN:
{
  "status": true/false, # status_code 200/400
  "errors": { # If "status" = false
    "user": {
      "FIELD": [ # "name","email","password","properties.value"
        "ERROR MESSAGE"
      ],
      "properties": [ # If exist custom fields
        {
          "custom_field_id": ID,
          "errors": {
            "value": [
              "ERROR MESSAGE"
            ]
          }
        }
      ]
    }
  }
}
Remove User

method: POST
URL: /management/users/ID/remove.json

PARAMETERS:
{
  "user": {
    "password": "PASSWORD", # If regular user (not Facebook user)
  }
}
RETURN:
{
  "status": true/false, # status_code 200/401
  "message": "ERROR MESSAGE" # If "status" = false
}
Reset Password

To reset an user password, you need to perform the following call:

method: POST
URL: /password_resets.json

PARAMETERS:
{
  “password_reset”: {
    “email”:  "EMAIL"
  }
}
RETURN:
{
  "status": TRUE
}
Subscriptions

Showing all subscriptions for an User:

method: GET
URL: /management/users/ID/subscriptions.json  # User ID on /management/users/info.json

PARAMETERS:
{
  “subscription_page”: “NUMBER” # Pagination, starting on 1
}
RETURN:
{
  "page": "subscriptions",
  "subscriptions": [
    {
      "SUBSCRIPTION INFORMATION"
    }
  ],
  "pagination": {
    "current": “NUMBER”, # Current page
    "last": true/false # Last page
  }
}

Showing a subscription for an User with Subscription ID:

method: GET
URL: /management/users/ID/subscriptions/ID/edit.json  # User ID on /management/users/info.json and Subscription ID on /management/users/ID/subscriptions.json

PARAMETERS:
RETURN:
{
  "page": "subscription",
  "subscription": [
    {
      "id": "ID", # NUMBER-TEXT
      "user_group_id": "SUBSCRIPTION PLAN ID", # NUMBER-TEXT (deprecated)
      "subscriptable_id": "SUBSCRIPTION PLAN ID", # NUMBER-TEXT
      "subscriptable_type": "UserGroup",
      "name": "NAME",
      "duration": "DURATION", # ["monthly"|"quarterly"|"triannually"|"semiannual"|"annual"|"biennial"|"perpetual"]
      "recurrent": true/false,
      "payment_method": "PAYMENT METHOD", # [“card”|”boleto”]
      "status": "PAYMENT STATUS", # [“trial”|“paid”|”pending”|”canceled”|”expired”]
      "current_period_start": “PAYMENT CYCLE START”, # yyyy-mm-dd
      "current_period_end": “PAYMENT CYCLE END”, # yyyy-mm-dd
      "suspended": true/false
      "price": “PRICE”, # In cents
      "installments": NUMBER, 
      "card_last_digits": “CARD LAST 4 DIGITS”, # If payment_method = “card”
      "invoice_url": "INVOICE URL", # If payment_method = “boleto”
      "invoice_expires_at": "INVOICE EXPIRES" # yyyy-mm-dd, if payment_method = “boleto”,
      "invoices": [
        {
          "date": "DATE", # yyyy-mm-dd
          "value": "VALUE", # In cents          
          "status": "STATUS", # [“paid”|”pending”|”expired”]
          "errors": {
            "code": "CODE",
            "date": "DATE",
            "text": "TEXT"
          }
        }
      ],
      "coupon": "COUPON INFO",
      "trial_days": NUMBER
    }
  ],
}

Next you have the request to change a credit card used on a subscription using the User ID

method: PUT
URL: /management/users/ID/subscriptions/ID.json  # User ID on /management/users/info.json

PARAMETERS:
{
  “card_token”: “TOKEN” 
}
RETURN:
{
  "status": true/false, # status_code 200/400
}

Here you can see how to cancel a subscription using the User ID

method: DELETE
URL: /management/users/ID/subscriptions/ID.json # User ID on /management/users/info.json

PARAMETERS:
{
  "subscription": {
    "password": "PASSWORD",
  }
}
RETURN:
{
  "status": true/false, # status_code 200/400
  "error": "ERROR MESSAGE" # If "status" = false
}

To reactivate a subscription before the expiration date:

method: POST
URL: /management/users/ID/subscriptions/ID/reactivate.json # User ID on /management/users/info.json

RETURN:
{
  "status": true/false, # status_code 200/400
}
TVODs

Showing all TVODs for an User:

method: GET
URL: /management/users/ID/tvods.json  # User ID on /management/users/info.json

PARAMETERS:
{
  “tvod_page”: “NUMBER” # Pagination, starting on 1
}
RETURN:
{
  "page": "tvods",
  "tvods": [
    {
      "TVOD INFORMATION"
    }
  ],
  "pagination": {
    "current": “NUMBER”, # Current page
    "last": true/false # Last page
  }
}

Showing a TVOD for an User with TVOD ID:

method: GET
URL: /management/users/ID/tvods/ID.json  # User ID on /management/users/info.json and TVOD ID on /management/users/ID/tvods.json

PARAMETERS:
RETURN:
{
  "page": "tvod",
  "tvod": [
    {
      "id": "ID", # NUMBER-TEXT
      "subscriptable_id": "TVOD ID", # NUMBER-TEXT
      "subscriptable_type": "Video|Audio",
      "name": "NAME",
      "duration": "DURATION", # ["purchase"|"rental"]
      "recurrent": true/false,
      "payment_method": "PAYMENT METHOD", # [“card”|”boleto”]
      "status": "PAYMENT STATUS", # [“paid”|”pending”|”expired”]
      "current_period_start": “PAYMENT CYCLE START”, # yyyy-mm-dd
      "current_period_end": “PAYMENT CYCLE END”, # yyyy-mm-dd
      "price": “PRICE”, # In cents
      "installments": NUMBER, 
      "card_last_digits": “CARD LAST 4 DIGITS”, # If payment_method = “card”
      "invoice_url": "INVOICE URL", # If payment_method = “boleto”
      "invoice_expires_at": "INVOICE EXPIRES" # yyyy-mm-dd, if payment_method = “boleto”,
      "invoices": [
        {
          "date": "DATE", # yyyy-mm-dd
          "value": "VALUE", # In cents
          "status": "STATUS", # [“paid”|”pending”|”expired”]
        }
      ]
    }
  ],
}
Leaderboards

method: GET
URL: /achievements/leaderboards.json

PARAMETERS:
{
  “user_rank_page”: “NUMBER” # Pagination, starting on 1
}
RETURN:
{
  "page": "leaderboards",
  "user_ranks": [
    {
      "position": NUMBER,
      "name": "NAME",
      "points": NUMBER
    }
  ],
  "pagination": {
    "current": “NUMBER”, # Current page
    "last": true/false # Last page
  }
}
<< Previous topic Next topic >>