The Grade.us API Version 4.0 is currently in Beta and is subject to change.

Endpoints

Users

The User object represents a user on the Grade.us application. This includes all types of Users, such as the Master user (primary owner), sub-Users (users with access to a subset of profiles owned by a master User), and independent Users (users that are sub-Users that have their own ability to provision their own Users). Master users are identified by the attribute “belongs_to_user_id” showing nil, while all other users will show the master users’ internal (not generally usable in API) Grade.us ID in this field.

Get Users

Description

Get a collection of all users that belongs to a master user.

Path

/users

Request 

Request
GET https://grade.us/api/v4/users

CURL
curl https://grade.us/api/v4/users -H "Authorization: API-KEY"

Response

Response code <200> 

{
  "users": [
    {
      "uuid": "17088031-5661-4154-a9ff-5a129f97b760",
      "email": "[email protected]",
      "first_name": "John",
      "last_name": "Doe",
      "belongs_to_domain": "",
      "permissions": [
        "admin"
      ],
      "custom_permissions": [

      ],
      "sign_in_count": 8,
      "current_sign_in_at": "2020-02-06T10:19:36.070-05:00",
      "last_sign_in_at": "2020-02-05T17:11:25.448-05:00",
      "current_sign_in_ip": "64.146.143.215",
      "last_sign_in_ip": "64.146.143.215",
      "created_at": "2019-12-12T12:00:52.928-05:00",
      "subscription_plan": "newnewagency",
      "status": null,
      "send_system_emails": true,
      "belongs_to_user_id": null,
      "belongs_to_independent_user_id": null,
      "mobile_number": "",
      "brands": [
        {
          "id": 98249,
          "title": "testname",
          "slug": "testapiexamplecom",
          "description": "",
          "blurb_a": "",
          "blurb_b": "",
          "theme_id": null,
          "palette_id": null,
          "logo_file_name": null,
          "logo_content_type": null,
          "logo_file_size": null,
          "logo_updated_at": null,
          "uuid": "490833d8-218c-4f28-936e-f171696e787d",
          "google_analytics_code": null,
          "domain": "testapi.example.com",
          "domain_status": "cname",
          "pending_domain": null,
          "switch_show_title": true,
          "switch_show_blurb_a": true,
          "switch_show_blurb_b": true,
          "switch_show_seal": true,
          "is_active": true,
          "is_demo": false,
          "created_at": "2020-01-17T16:30:01.271-05:00",
          "updated_at": "2020-01-17T16:30:01.781-05:00",
          "is_primary": true,
          "is_root": true,
          "location_reference": null,
          "locale": "en",
          "custom_css": null,
          "theme_template": "root",
          "index_template": null,
          "custom_seal_html": null,
          "category": null,
          "switch_noindex": false,
          "favicon_file_name": null,
          "favicon_content_type": null,
          "favicon_file_size": null,
          "favicon_updated_at": null,
          "icon_file_name": null,
          "icon_content_type": null,
          "icon_file_size": null,
          "icon_updated_at": null,
          "switch_show_multilingual": false,
          "home_uuid": "52134df0-c186-469c-b819-7bbb4c3a2a4c",
          "page_count": 1,
          "api_only": false,
          "redirect": null,
          "is_login_enabled": false,
          "is_secure": false,
          "logo_alt_file_name": null,
          "logo_alt_content_type": null,
          "logo_alt_file_size": null,
          "logo_alt_updated_at": null,
          "switch_show_location": false,
          "custom_head": null,
          "domain_is_shared": true,
          "belongs_to_domain": "",
          "switch_use_captcha": true,
          "creator_id": 51776,
          "creator_master_id": 51776,
          "notes": null,
          "custom_field1": null,
          "suspended": false,
          "background_image_url": "/assets/splash/rocket-launch.jpg",
          "default": false,
          "tracked": true,
          "internal_css": null,
          "support_url": null,
          "theme_name": "minimal",
          "google_tag_manager_container_id": null,
          "brand_color": "#f5f5f5",
          "switch_color_buttons_graphics": null,
          "header_image_file_name": null,
          "header_image_content_type": null,
          "header_image_file_size": null,
          "header_image_updated_at": null,
          "external_id": null,
          "group_id": null,
          "industry": "Auto & Car Dealer",
          "printable_card_image_file_name": null,
          "printable_card_image_content_type": null,
          "printable_card_image_file_size": null,
          "printable_card_image_updated_at": null,
          "privacy_policy_redirect": null
        }
      ],
      "profiles": [
        "a4d9b349-a318-47bf-99ce-a79c469fd878",
        "8d8e0b23-cdb3-4ee8-83d6-ab8b87e9a2aa",
        "e0242cfb-0bfc-4d1a-9ff3-b5885c87b51a",
        "52134df0-c186-469c-b819-7bbb4c3a2a4c"
      ]
    }
  ],
  "pagination": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1,
    "current_page_count": 0
  }
}

Get a User

Description

Get a specific user that belongs to logged in master user or master user

Path

/users/{user_uuid}

Params

Name Type Description
user_uuid String The unique UUID of a User.

Request 

Request
GET https://grade.us/api/v4/users/17088031-5661-4154-a9ff-5a129f97b760

CURL
curl https://grade.us/api/v4/users/17088031-5661-4154-a9ff-5a129f97b760 -H "Authorization: API-KEY"

Response

Response code <200> 

{
  "uuid": "17088031-5661-4154-a9ff-5a129f97b760",
  "email": "[email protected]",
  "first_name": "John",
  "last_name": "Doe",
  "belongs_to_domain": "",
  "permissions": [
    "admin"
  ],
  "custom_permissions": [

  ],
  "sign_in_count": 7,
  "current_sign_in_at": "2020-02-05T14:11:25.448-08:00",
  "last_sign_in_at": "2020-01-29T16:03:09.297-08:00",
  "current_sign_in_ip": "64.146.143.215",
  "last_sign_in_ip": "64.146.143.215",
  "created_at": "2019-12-12T09:00:52.928-08:00",
  "subscription_plan": "newnewagency",
  "status": null,
  "send_system_emails": true,
  "belongs_to_user_id": null,
  "belongs_to_independent_user_id": null,
  "mobile_number": "",
  "brands": [
    {
      "id": 98249,
      "title": "testname",
      "slug": "testapiexamplecom",
      "description": "",
      "blurb_a": "",
      "blurb_b": "",
      "theme_id": null,
      "palette_id": null,
      "logo_file_name": null,
      "logo_content_type": null,
      "logo_file_size": null,
      "logo_updated_at": null,
      "uuid": "490833d8-218c-4f28-936e-f171696e787d",
      "google_analytics_code": null,
      "domain": "testapi.example.com",
      "domain_status": "cname",
      "pending_domain": null,
      "switch_show_title": true,
      "switch_show_blurb_a": true,
      "switch_show_blurb_b": true,
      "switch_show_seal": true,
      "is_active": true,
      "is_demo": false,
      "created_at": "2020-01-17T13:30:01.271-08:00",
      "updated_at": "2020-01-17T13:30:01.781-08:00",
      "is_primary": true,
      "is_root": true,
      "location_reference": null,
      "locale": "en",
      "custom_css": null,
      "theme_template": "root",
      "index_template": null,
      "custom_seal_html": null,
      "category": null,
      "switch_noindex": false,
      "favicon_file_name": null,
      "favicon_content_type": null,
      "favicon_file_size": null,
      "favicon_updated_at": null,
      "icon_file_name": null,
      "icon_content_type": null,
      "icon_file_size": null,
      "icon_updated_at": null,
      "switch_show_multilingual": false,
      "home_uuid": "52134df0-c186-469c-b819-7bbb4c3a2a4c",
      "page_count": 1,
      "api_only": false,
      "redirect": null,
      "is_login_enabled": false,
      "is_secure": false,
      "logo_alt_file_name": null,
      "logo_alt_content_type": null,
      "logo_alt_file_size": null,
      "logo_alt_updated_at": null,
      "switch_show_location": false,
      "custom_head": null,
      "domain_is_shared": true,
      "belongs_to_domain": "",
      "switch_use_captcha": true,
      "creator_id": 51776,
      "creator_master_id": 51776,
      "notes": null,
      "custom_field1": null,
      "suspended": false,
      "background_image_url": "/assets/splash/rocket-launch.jpg",
      "default": false,
      "tracked": true,
      "internal_css": null,
      "support_url": null,
      "theme_name": "minimal",
      "google_tag_manager_container_id": null,
      "brand_color": "#f5f5f5",
      "switch_color_buttons_graphics": null,
      "header_image_file_name": null,
      "header_image_content_type": null,
      "header_image_file_size": null,
      "header_image_updated_at": null,
      "external_id": null,
      "group_id": null,
      "industry": "Auto & Car Dealer",
      "printable_card_image_file_name": null,
      "printable_card_image_content_type": null,
      "printable_card_image_file_size": null,
      "printable_card_image_updated_at": null
    }
  ],
  "profiles": [
    "02feb77f-2234-4015-b02d-051a5d752922",
    "f04902a7-319d-49c4-8a02-5d8b0210648e",
    "92e38646-8bc3-4691-84f9-87be582f55bf",
    "490833d8-218c-4f28-936e-f171696e787d"
  ]
}

Update User

Description

Updates a sub-User of a Master User. It is not possible to update or delete a Master User via the API.

Path

/users/{user_uuid}

Params

Name Type Description
last_name String The last name of the User.
user_uuid String The UUID of a User.

Request 

Request
PATCH https://grade.us/api/v4/users/17088031-5661-4154-a9ff-5a129f97b760  body: {"last_name":"Doe Jr."}

CURL
curl -d "last_name=Doe%20Jr." https://grade.us/api/v4/users/17088031-5661-4154-a9ff-5a129f97b760 -H "Authorization: API-KEY"

Response

Response code <404> 

{
  "status": "not_found",
  "error_code": 2002,
  "message": "Subuser does not exist."
}

Create User

Description

This endpoint creates a User. Newly created Users will receive an email asking them to confirm their account and set their password unless send_system_emails is set to “false”.

Path

/users/

Params

Name Type Description
belongs_to_domain
Optional
String Domain to associate this user with.
custom_permissions
Optional
Array An array of available features accessible to the User. The available options are ["funnel", "widgets", "invites", "reviews"].
Default: ["funnel", "widgets", "invites", "reviews"]
email String The User's email address, which must be unique within Grade.us. This email is used to login to the Grade.us application.
first_name
Optional
String The first name of the User.
last_name
Optional
String The last name of the User.
password
Optional
String The password for the User, used when logging into the Grade.us application. If this attribute is not provided, user access can be obtained through the Grade.us application by utilizing the login links for "Forgot your password?".
permissions
Optional
Array Permission dictate overall access to the Grade.us application. Values can include "admin" (all access), "staff" (all access except billing), "client" (access to certain profiles), or "independent" (access through a set brand).The permission "owner" will be on the master account, which can not be created by the API.
Default: ["client"]
profiles Array An array of profiles User can access.
send_system_emails
Optional
Bool Boolean value controlling whether system-generated emails, such as registration emails and other notifications, are sent to the User. If this value is true (default), a system-generated invitation email will be sent to the User to confirm their account. If this value is set to false, a user account does not go through the confirmation process and is immediately available for use. However, the user will need to retrieve their password by following the "Forgot password" process to obtain a password.
Default: true

Request 

Request
POST https://grade.us/api/v4/users/  body: {"email":"[email protected]","password":"password","first_name":"Sarah ","last_name":"Wilson","permissions":["client"],"send_system_emails":true,"profiles":["a4d9b349-a318-47bf-99ce-a79c469fd878"]}

CURL
curl -d "[email protected]&password=password&first_name=Sarah%20&last_name=Wilson&permissions=[%22client%22]&send_system_emails=true&profiles=[%22a4d9b349-a318-47bf-99ce-a79c469fd878%22]" https://grade.us/api/v4/users/ -H "Authorization: API-KEY"

Response

Response code <201> 

{
  "uuid": "223f51ea-de40-4bb5-b8e9-4e95e2b89f9f",
  "email": "[email protected]",
  "first_name": "Sarah ",
  "last_name": "Wilson",
  "belongs_to_domain": "",
  "permissions": [
    "client"
  ],
  "custom_permissions": [
    "funnel",
    "widgets",
    "invites",
    "reviews"
  ],
  "sign_in_count": 0,
  "current_sign_in_at": null,
  "last_sign_in_at": null,
  "current_sign_in_ip": null,
  "last_sign_in_ip": null,
  "created_at": "2020-02-05T16:45:45.380-06:00",
  "subscription_plan": "custom",
  "status": null,
  "send_system_emails": true,
  "belongs_to_user_id": 51776,
  "belongs_to_independent_user_id": null,
  "mobile_number": null,
  "brands": [

  ],
  "profiles": [
    "a4d9b349-a318-47bf-99ce-a79c469fd878"
  ]
}

Delete User

Description

Delete a sub-User. It is not possible to delete a Master User.

Path

/users/{user_uuid}

Params

Name Type Description
user_uuid String The unique User UUID.

Request 

Request
DELETE https://grade.us/api/v4/users/223f51ea-de40-4bb5-b8e9-4e95e2b89f9f

CURL
curl https://grade.us/api/v4/users/223f51ea-de40-4bb5-b8e9-4e95e2b89f9f -H "Authorization: API-KEY"

Response

Response code <200> 

{
  "message": "Successfully deleted user: [email protected]"
}

Get seat count

Description

Get current, used, seats and seat limits.

Path

/users/seat_count

Request 

Request
GET https://grade.us/api/v4/users/seat_count

CURL
curl https://grade.us/api/v4/users/seat_count -H "Authorization: API-KEY"

Response

Response code <200> 

{
  "seats_used": 1,
  "seats_limit": 5
}

Increment seat count

Description

Increase seat limit by one. In response will be shown new, increased, seat limit. Please keep in mind that charging will be performed accordingly.

Path

/users/increment_seat_count

Request 

Request
POST https://grade.us/api/v4/users/increment_seat_count

CURL
curl -d "" https://grade.us/api/v4/users/increment_seat_count -H "Authorization: API-KEY"

Response

Response code <200> 

{
  "message": "Successfully updated seat limit!. New seat limit: 5."
}

Profiles

Profile represent either a location, a business, or a service.

Get Profiles

Description

This returns all Profiles.

Path

/profiles/

Request 

Request
GET https://grade.us/api/v4/profiles/

CURL
curl https://grade.us/api/v4/profiles/ -H "Authorization: API-KEY"

Response

Response code <200> 

{
  "profiles": [
    {
      "id": "a4d9b349-a318-47bf-99ce-a79c469fd878",
      "parent_id": null,
      "name": "McDonalds",
      "short_name": "mcdee",
      "path": "mcdee/",
      "domain": "",
      "custom_field1": "",
      "notes": null,
      "children_profiles": [

      ],
      "created_at": "2019-12-13T03:10:36.641+10:00"
    },
    {
      "id": "8d8e0b23-cdb3-4ee8-83d6-ab8b87e9a2aa",
      "parent_id": null,
      "name": "My profile",
      "short_name": "myprofile",
      "path": "myprofile/",
      "domain": "",
      "custom_field1": null,
      "notes": null,
      "children_profiles": [

      ],
      "created_at": "2019-12-21T06:17:33.356+10:00"
    },
    {
      "id": "e0242cfb-0bfc-4d1a-9ff3-b5885c87b51a",
      "parent_id": null,
      "name": "testname",
      "short_name": "testname2",
      "path": "testname2/",
      "domain": "",
      "custom_field1": null,
      "notes": null,
      "children_profiles": [

      ],
      "created_at": "2020-01-18T07:26:04.618+10:00"
    }
  ],
  "pagination": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 3,
    "current_page_count": 3
  }
}

Get Profile

Description

This returns a specific Profile.

Path

/profiles/{profile_id}

Params

Name Type Description
profile_id String The UUID of a Profile.

Request 

Request
GET https://grade.us/api/v4/profiles/a4d9b349-a318-47bf-99ce-a79c469fd878

CURL
curl https://grade.us/api/v4/profiles/a4d9b349-a318-47bf-99ce-a79c469fd878 -H "Authorization: API-KEY"

Response

Response code <200> 

{
  "id": "a4d9b349-a318-47bf-99ce-a79c469fd878",
  "parent_id": null,
  "name": "McDonalds",
  "short_name": "mcdee",
  "path": "mcdee/",
  "domain": "",
  "custom_field1": "",
  "notes": null,
  "children_profiles": [

  ],
  "email": {
    "enabled": true,
    "mail_from_name": "Jone's Dentistry",
    "mail_from_address": null,
    "mail_reply_address": null,
    "unschedule_mail_on_click": true
  },
  "created_at": "2019-12-12T11:10:36.641-06:00"
}

Update Profile

Description

This updates a Profile.

Path

/profiles/{profile_id}

Params

Name Type Description
custom_field_1
Optional
String An optional string field that can be used for Tag or other labels.
notes
Optional
String
profile_id String The UUID of a Profile

Request 

Request
PATCH https://grade.us/api/v4/profiles/a4d9b349-a318-47bf-99ce-a79c469fd878  {:notes=>"Some generic notes", :custom_field_1=>"Important"}

CURL
curl -d "notes=Some%20generic%20notes&custom_field_1=Important" https://grade.us/api/v4/profiles/a4d9b349-a318-47bf-99ce-a79c469fd878 -H "Authorization: API-KEY"

Response

Response code <200> 

{
  "profile": {
    "id": "a4d9b349-a318-47bf-99ce-a79c469fd878",
    "parent_id": null,
    "name": "McDonalds",
    "short_name": "mcdee",
    "path": "mcdee",
    "domain": "",
    "custom_field_1": "",
    "notes": null,
    "created_at": "2019-12-12T12:10:36.641-05:00"
  }
}

Create Profile

Description

This endpoint creates a Profile. Certain attributes of a new Profile will be populated by standard defaults, but these attributes can also be sourced from a default profile that can be created manually in the Grade.us application.

Path

/profiles/

Params

Name Type Description
name String The name or title of a Profile.
parent_id
Optional
String If this ID of another Profile is included, then the new Profile will be added as a sub-Profile. Utilizing this attribute, will convert the parent Profile to be a multi-location Profile.

Request 

Request
POST https://grade.us/api/v4/profiles/  body: {"name":"Something New"}

CURL
curl -d "name=Something%20New" https://grade.us/api/v4/profiles/ -H "Authorization: API-KEY"

Response

Response code <200> 

{
  "id": "f5cc9088-2f52-4ce2-83d8-27de6237b36e",
  "parent_id": null,
  "name": "Something New",
  "short_name": "something-new",
  "path": "something-new/",
  "domain": "",
  "custom_field1": null,
  "notes": null,
  "children_profiles": [

  ],
  "created_at": "2020-01-21T10:06:38.777-05:00"
}

Delete Profile

Description

Delete a Profile.

Path

/profiles/{profile_id}

Params

Name Type Description
profile_id String The UUID of a Profile.

Request 

Request
DELETE https://grade.us/api/v4/profiles/f5cc9088-2f52-4ce2-83d8-27de6237b36e

CURL
curl https://grade.us/api/v4/profiles/f5cc9088-2f52-4ce2-83d8-27de6237b36e -H "Authorization: API-KEY"

Response

Response code <200> 

{
  "message": "Successfully deleted profile f5cc9088-2f52-4ce2-83d8-27de6237b36e."
}

Create phone

Description

Create a phone number for SMS sending

Path

/profiles/{profile_id}/create_phone

Params

Name Type Description
area_code
Optional
String The area code requested for a new number. Area code availability changes frequently with no guarantee that the area code requested will be available.
business_name
Optional
String The name of the business in which the phone number requested should be registered. This value is required in some countries, including Australia.
city
Optional
String The city of the company in which this number should be registered. This is required in some countries, including Australia.
country String Allowed values are 'US', 'CA', 'AU', or 'GB'.
postal_code
Optional
String The postal code of the company in which this number should be registered. This is required in some countries, including Australia.
profile_id String
region
Optional
String The region of the company in which this number should be registered. This is required in some countries, including Australia.
street_address
Optional
String The street address of the business in which the number should be registered. This is required in some countries, including Australia.

Request 

Request
POST https://grade.us/api/v4/profiles/a4d9b349-a318-47bf-99ce-a79c469fd878/create_phone  body: {"country":"US"}

CURL
curl -d "country=US" https://grade.us/api/v4/profiles/a4d9b349-a318-47bf-99ce-a79c469fd878/create_phone -H "Authorization: API-KEY"

Response

Response code <200> 

{
  "id": "a4d9b349-a318-47bf-99ce-a79c469fd878",
  "parent_id": null,
  "name": "McDonalds",
  "short_name": "mcdee",
  "path": "mcdee/",
  "domain": "",
  "custom_field1": "",
  "notes": null,
  "children_profiles": [

  ],
  "email": {
    "enabled": true,
    "mail_from_name": "McDonalds",
    "mail_from_address": null,
    "mail_reply_address": null,
    "unschedule_mail_on_click": true
  },
  "created_at": "2019-12-12T12:10:36.641-05:00"
}

Delete phone

Description

This deletes the phone number.

Path

/profiles/{profile_id}/delete_phone

Params

Name Type Description
profile_id
Optional
String

Request 

Request
PATCH https://grade.us/api/v4/profiles/a4d9b349-a318-47bf-99ce-a79c469fd878/disable_phone  body: {}

CURL
curl https://grade.us/api/v4/profiles/a4d9b349-a318-47bf-99ce-a79c469fd878/delete_phone -H "Authorization: API-KEY"

Response

Response code <200> 

{
  "id": "a4d9b349-a318-47bf-99ce-a79c469fd878",
  "parent_id": null,
  "name": "McDonalds",
  "short_name": "mcdee",
  "path": "mcdee/",
  "domain": "",
  "custom_field1": "",
  "notes": null,
  "children_profiles": [

  ],
  "phone": {
    "enabled": false,
    "country": "US",
    "phone_number": "(202) 929-6824"
  },
  "created_at": "2019-12-12T12:10:36.641-05:00"
}

Create Email

Description

Create ability to send Emails.

Path

/profiles/{profile_id}/create_email

Params

Name Type Description
delay_days String The time frame to send the first email in a campaign. If the value is '0', then sending will commence immediately.
Default: 0
mail_from_name String The default value is the title of the Profile.
profile_id String
unschedule_mail_on_click
Optional
String Deactivate a mail campaign if a recipient view a sent email.
Default: true

Request 

Request
POST https://grade.us/api/v4/profiles/a4d9b349-a318-47bf-99ce-a79c469fd878/create_email  body: {}

CURL
curl -d "" https://grade.us/api/v4/profiles/a4d9b349-a318-47bf-99ce-a79c469fd878/create_email -H "Authorization: API-KEY"

Response

Response code <200> 

{
  "id": "a4d9b349-a318-47bf-99ce-a79c469fd878",
  "parent_id": null,
  "name": "McDonalds",
  "short_name": "mcdee",
  "path": "mcdee/",
  "domain": "",
  "custom_field1": "",
  "notes": null,
  "children_profiles": [

  ],
  "email": {
    "enabled": true,
    "mail_from_name": "McDonalds",
    "mail_from_address": null,
    "mail_reply_address": null,
    "unschedule_mail_on_click": true
  },
  "created_at": "2019-12-12T12:10:36.641-05:00"
}

Delete Email

Description

Delete email on Profile

Path

/profiles/{profile_id}/delete_email

Params

Name Type Description
profile_id String The ID of the Profile.

Request 

Request
DELETE https://grade.us/api/v4/profiles/a4d9b349-a318-47bf-99ce-a79c469fd878/delete_email

CURL
curl https://grade.us/api/v4/profiles/a4d9b349-a318-47bf-99ce-a79c469fd878/delete_email -H "Authorization: API-KEY"

Response

Response code <200> 

{
  "id": "a4d9b349-a318-47bf-99ce-a79c469fd878",
  "parent_id": null,
  "name": "McDonalds",
  "short_name": "mcdee",
  "path": "mcdee/",
  "domain": "",
  "custom_field1": "",
  "notes": null,
  "children_profiles": [

  ],
  "created_at": "2019-12-12T12:10:36.641-05:00"
}

Find location candidates

Description

Find location listings based on provided Google CID. If a provided webhook URL found location candidates, they will be delivered to provided webhook URL. Check /profiles/{profile_id}/get_location_candidates for response body.

Path

/profiles/{profile_id}/find_location_candidates

Request 

Request
POST https://grade.us/api/v4/profiles/{profile_id}/find_location_candidates

{
    "google_cid" : "16591016107578133302",
    "web_hook_url": "https://d199e3c54d52.ngrok.io/webhooks"
}

CURL
curl -d "" https://grade.us/api/v4/profiles/{profile_id}/find_location_candidates -H "Authorization: API-KEY"

Response

Response code <200> 

{
  "location_id": "3c75559b2e93a18ef4774cb918e5282e",
  "status": "queued",
  "candidates": [

  ]
}

Get location candidates

Description

Get collected candidate locations from a previously initiated search on location via the “find_location_candidates” endpoint. “location_id” is a required parameter received from the “find_location_candidates” endpoint. If the operation is still in progress, candidates will return an empty array, and status will be “queued” or “working”.

Path

/profiles/{profile_id}/get_location_candidates

Request 

Request
GET https://grade.us/api/v4/profiles/{profile_id}/get_location_candidates

{
    "location_id": "3c75559b2e93a18ef4774cb918e5282e"
}

CURL
curl https://grade.us/api/v4/profiles/{profile_id}/get_location_candidates -H "Authorization: API-KEY"

Response

Response code <200> 

// When location candidates searching completed:
{
    "location_id": "3c75559b2e93a18ef4774cb918e5282e",
    "status": "completed",
    "candidates": [
        {
            "category": "facebook",
            "label": "Facebook",
            "status": "success",
            "locations": [
                {
                    "url": "https://www.facebook.com/PausAsianKitchen",
                    "id": "PausAsianKitchen",
                    "title": "Pau's Asian Kitchen",
                    "address1": "321 High School Rd",
                    "locality": "Bainbridge Island",
                    "region": "WA",
                    "postal_code": "98110"
                }
            ]
        },
        {
            "category": "foursquare",
            "label": "Foursquare",
            "status": "success",
            "locations": [
                {
                    "url": "https://foursquare.com/v/594b292a04d1ae5204d378c6",
                    "id": "594b292a04d1ae5204d378c6",
                    "title": "Pau's Asian Kitchen",
                    "address1": "321 High School Rd NE Ste D6",
                    "locality": "Bainbridge Island",
                    "region": "WA",
                    "postal_code": "98110",
                    "latitude": 47.634769439697266,
                    "longitude": -122.51746368408203
                }
            ]
        },
        {
            "category": "google",
            "label": "Google",
            "status": "success",
            "locations": [
                {
                    "url": "https://maps.google.com/?cid=16591016107578133302",
                    "id": "ChIJ99agCqM-kFQRNov6Mj8hP-Y",
                    "title": "Pau's Asian Kitchen",
                    "address1": "321 High School Rd NE D-6",
                    "locality": "Bainbridge Island",
                    "region": "WA",
                    "latitude": 0.0,
                    "longitude": 0.0,
                    "category": "restaurant"
                }
            ]
        },
        {
            "category": "yelp",
            "label": "Yelp",
            "status": "success",
            "locations": [
                {
                    "url": "http://www.yelp.com/biz/paus-asian-kitchen-bainbridge-island",
                    "id": "zr2w6zfmCp7F_dmmQs-44w",
                    "title": "Pau's Asian Kitchen",
                    "address1": "321 High School Rd NE",
                    "locality": "Bainbridge Island",
                    "region": "WA",
                    "postal_code": "98110",
                    "latitude": 47.634887,
                    "longitude": -122.517384
                }
            ]
        },
        {
            "category": "yp",
            "label": "YP.com",
            "status": "success",
            "locations": [
                {
                    "url": "http://www.yellowpages.com/l/539008259",
                    "id": "539008259",
                    "title": "Pau's Asian Kitchen",
                    "address1": "321 High School Rd NE Suite D",
                    "locality": "Bainbridge Island",
                    "region": "WA",
                    "postal_code": "98110"
                }
            ]
        }
    ]
}

// When location candidates searching still in progress:
{
    "location_id": "4be81965231b01210cb43e65565dc567",
    "status": "working",
    "candidates": []
}

Add location candidates

Description

Add subset of found candidate locations to a given Profile using the previous “find_location_candidates” endpoint.

Path

/profiles/{profile_id}/add_location_candidates

Request 

Request
POST https://grade.us/api/v4/profiles/{profile_id}/add_location_candidates

{
    "location_id": "3c75559b2e93a18ef4774cb918e5282e",
     "candidates": [
        {
            "category": "facebook",
            "id": "PausAsianKitchen"    
        },
        {
            "category": "foursquare",
            "id": "594b292a04d1ae5204d378c6"    
        },
        {
            "category": "yelp",
            "id": "zr2w6zfmCp7F_dmmQs-44w"    
        },
        {
            "category": "google",
            "id": "ChIJ99agCqM-kFQRNov6Mj8hP-Y"    
        }
    ]
}

CURL
curl -d "" https://grade.us/api/v4/profiles/{profile_id}/add_location_candidates -H "Authorization: API-KEY"

Response

Response code <200> 

{
  "message": "Location candidates are being added. Check your profile later."
}

Ratings distribution by sentiment

Description

Ratings distribution by sentiment

Path

/profiles/{profile_id}/ratings_distribution_by_sentiment

Request 

Request

CURL
curl https://grade.us/api/v4/profiles/{profile_id}/ratings_distribution_by_sentiment -H "Authorization: API-KEY"

Response 

{
  "positive": 12944,
  "neutral": 39,
  "negative": 51
}

Ratings distribution by site

Description

Ratings distribution by site

Path

/profiles/{profile_id}/ratings_distribution_by_site

Request 

Request

CURL
curl https://grade.us/api/v4/profiles/{profile_id}/ratings_distribution_by_site -H "Authorization: API-KEY"

Response 

{
  "vitals": {
    "review_count": 10,
    "avg_rating": 5.0
  },
  "booking": {
    "review_count": 12729,
    "avg_rating": 4.989331447874929
  },
  "cargurus": {
    "review_count": 239,
    "avg_rating": 4.2259414225941425
  },
  "amazon": {
    "review_count": 55,
    "avg_rating": 4.4
  }
}

Ratings distribution by star

Description

Ratings distribution by star

Path

/profiles/{profile_id}/ratings_distribution_by_star

Request 

Request

CURL
curl https://grade.us/api/v4/profiles/{profile_id}/ratings_distribution_by_star -H "Authorization: API-KEY"

Response 

{
  "five": 12863,
  "four": 81,
  "three": 39,
  "two": 19,
  "one": 32
}

Reviews

Reviews are collected by Grade.us from sources that are provided through the Links resource.

Get Reviews

Description

Get all Reviews.

Path

/profiles/{profile_id}/reviews/

Params

Name Type Description
profile_id String

Request 

Request
GET https://grade.us/api/v4/profiles/a4d9b349-a318-47bf-99ce-a79c469fd878/reviews/

CURL
curl https://grade.us/api/v4/profiles/a4d9b349-a318-47bf-99ce-a79c469fd878/reviews/ -H "Authorization: API-KEY"

Response

Response code <200> 

{
  "reviews": [
    {
      "id": "174c2425-f462-4b6e-9d9e-879db583cca5",
      "unique_id": "116214088871125344044",
      "category": "google",
      "date": "2020-01-01T11:45:20.000-06:00",
      "rating": 4.0,
      "attribution": "Stephen Hinson",
      "title": null,
      "content": "Excellent service from scheduling, convenience and the result. A bit pricey but that’s what you pay for ease and outcome.",
      "url": "http://search.google.com/local/writereview?placeid=ChIJlSIb2ZRmZIgRShYHsUPW-NU",
      "created_at": "2020-01-08T11:45:25.541-06:00"
    },
    {
      "id": "22ca4d58-8f40-4f17-a94e-e2c46e873423",
      "unique_id": "108467467483720766165",
      "category": "google",
      "date": "2019-12-18T11:45:20.000-06:00",
      "rating": 5.0,
      "attribution": "Rob Ruzicka",
      "title": null,
      "content": "I have been using Aussie Pet Mobile since 2010 and have really been satisfied with their services and groomers. Sebastian stresses out riding in the car so having them come to my place works out really well. They def aren't the most reasonable but when it comes to Sebastian and how they care for him it;s totally worth every penny. Sebastian loved his former groomer Rachelle at Aussie but she moved away. Now his new groomer Lauren is awesome and I am glad he feels comfortable with her giving him a stress free haircut and bath. Def give them a try when you want the very best for you cat or dog!",
      "url": "http://search.google.com/local/writereview?placeid=ChIJlSIb2ZRmZIgRShYHsUPW-NU",
      "created_at": "2020-01-08T11:45:25.578-06:00"
    },
    {
      "id": "11d5d3b2-91ca-4554-99e9-a3fea0e16240",
      "unique_id": "108645385002145733315",
      "category": "google",
      "date": "2019-12-08T11:45:20.000-06:00",
      "rating": 5.0,
      "attribution": "Mark Kelly",
      "title": null,
      "content": "Great price and awesome service. The only issue is it can be a little difficult to get an appointment, sometimes taking a month or so. But they have a wait list and are usually able to accommodate!",
      "url": "http://search.google.com/local/writereview?placeid=ChIJlSIb2ZRmZIgRShYHsUPW-NU",
      "created_at": "2020-01-08T11:45:25.653-06:00"
    },
    {
      "id": "744e989a-55bd-48d8-8a66-b0210b2c68fc",
      "unique_id": "117068420619110007466",
      "category": "google",
      "date": "2019-12-08T11:45:20.000-06:00",
      "rating": 5.0,
      "attribution": "Kathy Ross",
      "title": null,
      "content": "Keith is a wonderful groomer and our Emma does not like “anything done to her”! She totally trusts Keith and is always so beautiful after her “spa” morning!We appreciate that Keith is always so punctual and patient with our princess!Thanks, Aussie Pet Mobile!Kathy Ross",
      "url": "http://search.google.com/local/writereview?placeid=ChIJlSIb2ZRmZIgRShYHsUPW-NU",
      "created_at": "2020-01-08T11:45:25.925-06:00"
    },
    {
      "id": "002474d3-4976-4dee-bbbc-fc833a8f7f0e",
      "unique_id": "102633421124055576267",
      "category": "google",
      "date": "2019-12-08T11:45:20.000-06:00",
      "rating": 5.0,
      "attribution": "Stefanie O'Reilly Stricker",
      "title": null,
      "content": "We have used Aussie for a year now, and we absolutely love them. Our two dogs are always excited to see their groomer, Reve, who is patient, kind, and detail-oriented. Reve does a beautiful job with hair cuts and even gets lots of tail-wagging from our slightly nervous 7 year-old lab mix. We love the convenience of having Aussie come to our home and of having a pre-planned year-long schedule. The office staff and groomer always provide great customer service and are a pleasure to work with every time.",
      "url": "http://search.google.com/local/writereview?placeid=ChIJlSIb2ZRmZIgRShYHsUPW-NU",
      "created_at": "2020-01-08T11:45:25.755-06:00"
    },
    {
      "id": "b0110fb4-9b81-45c9-be8d-6f36cdae2eee",
      "unique_id": "115500661296713177409",
      "category": "google",
      "date": "2019-12-08T11:45:20.000-06:00",
      "rating": 5.0,
      "attribution": "LeNisha Walker",
      "title": null,
      "content": "Destiny did such a wonderful job with my pup. His cut is the cutest and he smells awesome!",
      "url": "http://search.google.com/local/writereview?placeid=ChIJlSIb2ZRmZIgRShYHsUPW-NU",
      "created_at": "2020-01-08T11:45:25.962-06:00"
    }
  ],
  "pagination": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 6,
    "current_page_count": 6
  }
}

Recipients

Recipients are people that will be sent a campaign of email and/or SMS’s requesting review.

Get Recipients

Description

Get all Recipients.

Path

/profiles/{profile_id}/recipients

Params

Name Type Description
profile_id String

Request 

Request
GET https://grade.us/api/v4/profiles/a4d9b349-a318-47bf-99ce-a79c469fd878/recipients

CURL
curl https://grade.us/api/v4/profiles/a4d9b349-a318-47bf-99ce-a79c469fd878/recipients -H "Authorization: API-KEY"

Response

Response code <200> 

{
  "recipients": [
    {
      "id": "e391b862-4872-11ea-abb0-4a8a1824297b",
      "rating_data": {
        "first": {
          "rating": 8,
          "created_at": "2019-07-05T13:39:58.279-04:00"
        },
        "last": {
          "rating": "N/A",
          "created_at": "N/A"
        }
      },
      "email_address": "[email protected]",
      "phone_number": null,
      "first_name": "John",
      "last_name": "Doe",
      "sent_count": 3,
      "started_at": "2020-02-05T18:54:46.938-05:00",
      "last_sent_at": "2020-02-12T10:09:29.297-05:00",
      "is_pending": false,
      "is_active": false,
      "is_archived": true,
      "rejected": false,
      "blocked": false,
      "bounced": false,
      "clicked": false,
      "flagged": false,
      "opened": true,
      "unsubscribed": false,
      "custom_field_1": null
    }
  ],
  "pagination": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 0,
    "total_count": 0,
    "current_page_count": 0
  }
}

Get Recipient

Description

Get a Recipient. Rating data of the recipient will be shown under “rating-data” key. If there is multiple rating results first and last one will be shown in response. Rating will be normalised to range values from 0 to 10.

Path

/profiles/{profile_id}/recipients/{recipient_id}

Params

Name Type Description
profile_id String
recipient_id String

Request 

Request
GET https://grade.us/api/v4/profiles/a4d9b349-a318-47bf-99ce-a79c469fd878/recipients/e391b862-4872-11ea-abb0-4a8a1824297b

CURL
curl https://grade.us/api/v4/profiles/a4d9b349-a318-47bf-99ce-a79c469fd878/recipients/e391b862-4872-11ea-abb0-4a8a1824297b -H "Authorization: API-KEY"

Response

Response code <200> 

{
  "id": "e391b862-4872-11ea-abb0-4a8a1824297b",
  "rating_data": {
    "first": {
      "rating": 8,
      "created_at": "2019-07-05T13:39:58.279-04:00"
    },
    "last": {
      "rating": "N/A",
      "created_at": "N/A"
    }
  },
  "email_address": "[email protected]",
  "phone_number": null,
  "first_name": "John",
  "last_name": "Doe",
  "sent_count": 3,
  "started_at": "2020-02-05T18:54:46.938-05:00",
  "last_sent_at": "2020-02-12T10:09:29.297-05:00",
  "is_pending": false,
  "is_active": false,
  "is_archived": true,
  "rejected": false,
  "blocked": false,
  "bounced": false,
  "clicked": false,
  "flagged": false,
  "opened": true,
  "unsubscribed": false,
  "custom_field_1": null
}

Create Recipients

Description

Create one or more Recipients. Prior to creating a Recipient, phone and/or email service must be enabled.

Path

/profiles/{profile_id}/recipients

Params

Name Type Description
email_address
Optional
String The email address of the Recipient, if an email campaign is desired.
first_name
Optional
String First name of Recipient.
last_name
Optional
String Last name of Recipient.
profile_id String

Request 

Request
POST https://grade.us/api/v4/profiles/a4d9b349-a318-47bf-99ce-a79c469fd878/recipients  body: {"recipients":[{"email_address":"[email protected]"}]}

CURL
curl -d "recipients=[%7B:email_address=%3E%[email protected]%22%7D]" https://grade.us/api/v4/profiles/a4d9b349-a318-47bf-99ce-a79c469fd878/recipients -H "Authorization: API-KEY"

Response

Response code <422> 

{
  "results": [

  ],
  "errors": [
    "Dropped [email protected] (Recipient already exists)"
  ],
  "notices": [

  ]
}