The Amp Devcenter Test Developer Hub

Welcome to the Amp Devcenter Test developer hub. You'll find comprehensive guides and documentation to help you start working with Amp Devcenter Test as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

User Profile API

The User Profile API serves Amplitude User Profiles, which includes user properties, computed user properties, a list of cohort IDs of cohorts that the user is in, and recommendations.

Authentication

The Profile API currently supports API Key authentication by setting an Authorization header. The authentication used for this API differs from many of the other APIs:

{
  "Authorization": "Api-Key <api_secret_key>"
}

Endpoint

https://profile-api.amplitude.com/v1/userprofile

Parameters

ParameterDescription
user_id (optional)User id (external database id) to be queried, required unless device_id is set.
device_id (optional)Device id (anonymous id) to be queried, required unless user_id is set.
get_recs (optional, default=false)Return a recommendation result for this user.
rec_id (optional)Recommendation(s) to be retrieved, required if get_recs is true. Multiple recommendations can be fetched by separating the rec_ids with commas.
rec_type (optional)Overrides the default experimental control setting and rec_type=model will return modeled recommendations and rec_type=random return random recommendations. Other options may exist in the future.
get_amp_props (optional, default=false)Return a full set of user properties for this user, not including computations
get_cohort_ids (optional, default=false)Return a list of all of the cohort IDs that this user is a part of that have been set up to be tracked. By default cohort membership is not tracked for users for any cohort.
get_computations (optional, default=false)Return a list of all of the computations that are enabled for this user
comp_id (optional)Return a single computation that might be enabled for this user. It will return a null value if it does not exist. If get_computations is true, all values will be fetched, including this one (unless it is archived or deleted).

Examples

Get a Recommendation

Endpoint

https://profile-api.amplitude.com/v1/userprofile?user_id=testUser&get_recs=true&rec_id=testRecId

Response

{
  "userData": {
    "recommendations": [
      {
        "rec_id": "testRecId",
        "child_rec_id": "testRecId",
        "items": [
          "cookie",
          "cracker",
          "chocolate milk",
          "donut",
          "croissant"
        ],
        "is_control": false,
        "recommendation_source": "model",
        "last_updated": 1608670720
      }
    ],
    "user_id": "testUser",
    "device_id": "ffff-ffff-ffff-ffff",
    "amp_props": null,
    "cohort_ids": null
  }
}
Response ParameterDescription
rec_idThe recommendation id that was requested.
child_rec_idA more detailed recommendation id that we may use on the backend as part of an internal experiment to improve model performance. In most cases this will be the same as rec_id.
itemsList of recommendations for this user.
is_controltrue if this user is part of the control group
recommendation_sourceName of the model that was used to generate this recommendation
last_updatedTimestamp of when this recommendation was last generated and synced

Get Multiple Recommendations

Endpoint

https://profile-api.amplitude.com/v1/userprofile?user_id=testUser&get_recs=true&rec_id=testRecId,testRecId2

Response

{
  "userData": {
    "recommendations": [
      {
        "rec_id": "testRecId",
        "child_rec_id": "testRecId",
        "items": [
          "cookie",
          "cracker",
          "chocolate milk",
          "donut",
          "croissant"
        ],
        "is_control": false,
        "recommendation_source": "model",
        "last_updated": 1608670720
      },
            {
        "rec_id": "testRecId2",
        "child_rec_id": "testRecId2",
        "items": [
          "bulgogi",
          "bibimbap",
          "kimchi",
          "croffles",
          "samgyeopsal"
        ],
        "is_control": false,
        "recommendation_source": "model2",
        "last_updated": 1608670658
      }
    ],
    "user_id": "testUser",
    "device_id": "ffff-ffff-ffff-ffff",
    "amp_props": null,
    "cohort_ids": null
  }
}

Get User Properties

Endpoint

https://profile-api.amplitude.com/v1/userprofile?user_id=testUser&get_amp_props=true

Response

{
  "userData": {
    "recommendations": null,
    "user_id": "testUser",
    "device_id": "ffff-ffff-ffff-ffff",
    "amp_props": {
      "library": "http/1.0",
      "first_used": "2020-01-13",
      "last_used": "2021-03-24",
      "number_property": 12,
      "boolean_property": true
    },
    "cohort_ids": null
  }
}

Get Cohort IDs

Endpoint

https://profile-api.amplitude.com/v1/userprofile?user_id=testUser&get_cohort_ids=true

Response

{
  "userData": {
    "recommendations": null,
    "user_id": "testUser",
    "device_id": "ffff-ffff-ffff-ffff",
    "amp_props": null,
    "cohort_ids": ["cohort1", "cohort3", "cohort7"]
  }
}

Get a Single Computation

Endpoint

https://profile-api.amplitude.com/v1/userprofile?user_id=testUser&comp_id=testCompId

Response

{
  "userData": {
    "recommendations": null,
    "user_id": "testUser",
    "device_id": "ffff-ffff-ffff-ffff",
    "amp_props": {
      "computed-prop-2": "3"
    },
    "cohort_ids": null
  }
}

Get all Computations

Endpoint

https://profile-api.amplitude.com/v1/userprofile?user_id=testUser&get_computations=true

Response

{
  "userData": {
    "recommendations": null,
    "user_id": "testUser",
    "device_id": "ffff-ffff-ffff-ffff",
    "amp_props": {
      "computed-prop-1": "5000000.0",
      "computed-prop-2": "3"
    },
    "cohort_ids": null
  }
}

Get a Single Prediction Propensity Score

Endpoint

https://profile-api.amplitude.com/v1/userprofile?user_id=testUser&get_propensity=true&propensity_type=score&prediction_id=testPrediction

Response

{
  "userData": {    
    "recommendations": null,
    "user_id": "testUser",
    "device_id": "ffff-ffff-ffff-ffff",
    "amp_props": {
      "computed-prop-2": "3"
    },
    "propensity": 0.500001
  }
}

Get a Single Prediction Propensity Percentile

https://profile-api.amplitude.com/v1/userprofile?user_id=testUser&get_propensity=true&propensity_type=pct&prediction_id=testPrediction

Response

{
  "userData": {
    "recommendations": null,
    "user_id": "testUser",
    "device_id": "ffff-ffff-ffff-ffff",
    "amp_props": {
      "computed-prop-2": "3"
    },
    "propensity": 83
  }
}

Common Gotchas in Integrating with the User Profile API

Forgetting to use the “is_control” flag

If you don’t serve your default user experience for users with “is_control” = “true”, we won’t be able to measure performance

Not serving a default experience in the case of error responses

There are two common error responses from the API:

  • When the user just signed up (< 5 min ago), you will likely get a response:
{"error":"User id and device id not seen before"}
  • If a user is < 2 hours old or has been inactive > 90 days, they will have an API response but return
"recommendations": null”
  • If we are having maintenance or some kind of issue and return a 500. You can retry or serve the default experience.

In all of these cases, make sure to default to your baseline experience

Authentication errors

  • If the Secret Key is correct but User IDs are not of the proper form, or are User IDs from a different project, you will get a response:
{"error":"User id and device id not seen before"}
  • If the Secret Key is incorrect, you will get an error (HTTP 401) response:
Invalid Api-Key
  • If the Authorization header is missing or malformed you will get an error (HTTP 401) response:
Missing Api-Key in Authorization header

Configuration errors

  • If the endpoint or path are incorrect you will get an empty error (HTTP 404) response
  • If an insecure http request is sent, it will be redirected to the https endpoint (HTTPS 301) with an HTML body - the Location header contains the proper protocol and URL
    301 Moved Permanently

Updated 6 days ago


User Profile API


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.