Article sections

    API Overview

    We use a RESTful API, in which all endpoints are prefixed with the API version and a unique hash identifying your shop.

    http://api.reveal.omniconvert.com/v1/s/shpdmo/…

    The v1​ part indicated you’re using the version 1 of the API, while the shpdmo​ represents the unique alphanumeric hash identifying your shop. However, the login endpoint does not contain this unique, as it is performed outside a shop context.

    API Authentication

    Our API is secured using JWT token, so before anything else, will first need to authenticate:

    POST http://api.reveal.omniconvert.com/v1/login
    Body: {
      "username": "your_username",
      "key": "your_api_key"
    }
    Headers: Content-type: application/json

    As a response, you will receive something similar to:

    {
        "code": 200,
        "expire": "2019-06-03T08:05:34Z",     
        "token": "K0FIc0FJZy1hb...K0FDSS10eXBlK0FDSTorQUNJQUlnQjlBQWcg"
    }
    

    The token expires after 1 hour and it must be used in all subsequent API requests.

    Customer RFM

    Endpoints

    To fetch the complete list of customers with their associated RFM information you can call:

    • GET http://api.reveal.omniconvert.com/v1/s/shpdmo/rfm/download/customers.csv
    • GET http://api.reveal.omniconvert.com/v1/s/shpdmo/rfm/download/customers.json
    Headers: Authorization:"Bearer token here"

    The shpdmo part of the URL must be substituted with your shop unique ID, which you can find in the URL of your Reveal Dashboard.

    Customer data structure – export

    Attribute Type Limits Description
    customer_eid string 255 The identifier you have defined for the customer
    email string 255 The email of the customer
    first_name string 255 First name
    last_name string 255 Last name
    rfm_score string 3 3-digit score
    rfm_group_id int Ther RFM Group id
    rfm_group_name string 255 The name of the RFM Group
    {
        "customers_rfm": [
            {
                "custom_attributes": null,
                "customer_eid": "1894",
                "customer_email": "[email protected]",
                "customer_first_name": "Horace",
                "customer_last_name": "Kshlerin",
                "profit": null,
                "revenue": null,
                "rfm_group_id": null,
                "rfm_group_name": null,
                "rfm_score": ""
            },
            {
                "custom_attributes": null,
                "customer_eid": "1916",
                "customer_email": "[email protected]",
                "customer_first_name": "Coy",
                "customer_last_name": "Cummerata",
                "profit": 27.8219,
                "revenue": 140.08,
                "rfm_group_id": 8,
                "rfm_group_name": "Breakup",
                "rfm_score": "112"
            },
    }

    Customers with rfm_group_id ​and rfm_group_name containing ​null values must also be taken into account. They placed an order, but then canceled it, so they are not eligible for RFM segmentation. The RFM score and segmentation must be updated (removed) for them.

    NPS Invitations

    Endpoints

    To fetch the list of daily generated NPS Invitations (the list can also be empty if no NPS Invitation could be generated for that day, say no new orders or no one passed the capping rules):

    • GET
      http://api.reveal.omniconvert.com/v1/s/shpdmo/nps/download/daily_invitations.csv
    • GET
      http://api.reveal.omniconvert.com/v1/s/shpdmo/nps/download/daily_invitations.json
     Headers: Authorization: "Bearer token here"

    The shpdmo part of the URL must be substituted with your shop unique ID, which you can find in the URL of your Reveal Dashboard.

    NPS Invitation data structure – export

    Column Type Description
    nps_unique string The identifier of the NPS Invitation; just in case you want to mark it as sent through API
    customer_eid string The identifier you have defined for the customer
    customer_email string The customer email
    customer_first_name string
    customer_last_name string
    status string The status of the invitation:
    to_send,
    not_sent,
    sent,
    consumed,
    expired.
    send_until string DateTime in format YYYY-MM-dd HH:mm:ss
    nps_open_link string The link that should be added in email as a “tracking” pixel, in order to measure the email open rate
    nps_link string The link of the NPS
    nps_link_0 string The link of the NPS with prefilled overall score = 0; to use in email in grid
    nps_link_1 string The link of the NPS with prefilled overall score = 1; to use in email in grid
    nps_link_10 string The link of the NPS with prefilled overall score = 10; to use in email in grid
    nps_list_id int If is part of an NPS Invitations List
    rfm_score string The RFM score of the customer for the moment when he placed the order (that order included)
    rfm_group_id int The RFM Group Id of the customer for the moment when he placed the order (that order included)
    rfm_group_name string The RFM Group name of the customer for the moment when he placed the order (that order included)

    NPS Invitation API methods

    Create & Delete

    These methods are not immplemented, since they have no real use. The NPS Invitation is created automatically and cannot be deleted.

    Mark as sent

    Method: POST /nps-invitations/{nps_invitation_unique}/mark-sent
    Body: empty
    Response: 200 with nps_invitation object, or error status with error message

    This will also update the NPS Invitation List to “mark as sent” if this was the last unsent NPS
    Invitation in the list, so the data will be consistent.

    Show

    Method: GET /nps-invitations/{nps_invitation_unique}
    Body: empty
    Response: 200 with nps_invitation object, or error status with error message

    List

    Method: GET /nps-invitations?filters&page
    Body: empty
    Response: 200 with page object, or error status with error message

    You can filter the nps_invitations by:

    Attribute Type Description
    status string One of:
    to_send,
    not_sent,
    sent,
    consumed,
    expired.

    One thing to notice, if you don’t use the “mark as sent” feature, a NPS Invitation can transition from to_send in not_sent then in consumed.
    customer_eid string The unique identifier you have defined for the customer
    customer_email string Customer email
    order_eid string The unique identifier you have defined for the order
    nps_invitations_list_id int The id of the NPS Invitation List the invitations were included in.
    rfm_score string
    rfm_group int
    Invitation data structure – API
    Attribute Type Description
    id int The id of the invitation
    unique string The unique generated for this invitation
    link string The link of the NPS; you can add to it &q=X for prefilling the overall score with X, where X is between 0-10
    customer_eid string The unique identifier you have defined for the customer
    customer_email string Customer email
    customer_first_name string
    customer_last_name string
    order_eid string The unique identifier you have defined for the order, you may need it for your internal tracking
    nps_invitations_list_id int
    rfm_score string
    rfm_group_id int
    send_until datetime
    sent_at
    consumed_at
    status string The status of the invitation:
    to_send,
    not_sent,
    sent,
    consumed,
    expired.

    You should email the invitation only when the status is “to_send”, otherwise you risk sending it twice, too late or even after it was consumed. Also you should use the “mark as sent” feature for the invitations you sent, otherwise you will risk seeing again in the “to_send” status and send them twice or more.

    Export

    Method: GET /nps/export/invitations.{format}?filter
    Body: empty
    Response: 200 status, or error status
    CSV or JSON file with structure described at the beginning of chapter.
    The returned list is composed of all to_send NPS Invitations (unless otherwise specified in filter).
    Note the list_id field, which tells you if that invitation is part of an NPS Invitation List, which probably you downloaded before and maybe already sent it. We recommend to use one of the 2 variants, individual invites or lists to avoid double sends or skipping some emails.
    The export data structure is the one in NPS Invitation data structure – export section above

    Bulk Mark as sent

    Method: POST /bulk/nps-invitations/mark-sent
    Body:

    {
        "nps_invitations": [
            nps_invitation_unique,
            nps_invitation_unique,
         ]
    }

    Response: 204 status, or error status with error message

    The data structure supports multiple nps_invitations uniques, defined in the array under “nps_invitations” key. For a better tracking it is your responsibility to perform this call for all the NPSInvitations for which the email was sent. You can also use the NPSInvitationList “mark as sent” feature.

    NPS Invitation List data structure

    Attribute Type Description
    id int The id of the invitation list
    status string The NPS Invitation List status, one of:
    to_send,
    not_sent,
    sent.

    Even if the status is to_send or not_sent, there might be some NPS Invitations in it that are sent, because they were “marked as sent” individually, and also some other NPS Invitations that are in fact sent but with status not updated. So it’s a good idea to use the “mark as sent” feature. If the status is sent, it means all the invitations are also “marked as sent”, but it is in your job to actually send them, we just want to help you track the progress.
    send_until datetime
    sent_at datetime
    nps_invitations array Array with nps_invitation objects, but only with unique and status field.

    NPS Invitation List API methods

    Create & Delete

    These methods have no use. The NPS Invitation List is created automatically and cannot be deleted.

    Mark as sent

    Method: POST
    /nps-invitations-lists/{nps_invitations_list_id}/mark-sent

    Body: empty
    Response: 200 with nps_invitations_list object, or error status with error message

    This will update all the NPS Invitations in the list to “mark as sent” so the data will be consistent. If the status is already “consumed”, it will return a 409.

    Show

    Method: GET /nps-invitations-lists/{nps_invitations_list_id}
    Body: empty
    Response: 200 with nps_invitations_list object, or error status with error message

    List

    Method: GET /nps-invitations-lists?filters&page
    Body: empty
    Response: 200 with page object, or error status with error message

    You can use this instead of daily feed, he will get here all the lists even if they were generated from GUI. Then use the nps_invitations API method list to get the actual invitations.

    You can filter the nps_invitations_lists by:

    Attribute Type Description
    status string One of:
    to_send,
    not_sent,
    sent,

    Remember to use the “mark as sent” feature for an accurate response

    Bulk Mark as sent

    Method: POST /bulk/nps-invitations-lists/mark-sent
    Body:

     {
        "nps_invitations_lists": [
            nps_invitations_list_id,
            nps_invitations_list_id,
        ]
    } 

    Response: 204 status, or error status with error message