Skip to main content

Note: Not all the account related fields are returned for an authenticated user. The fields returned in the response are controlled by the scopes and are available only to select developers approved by business units.

The Identity API returns data for an authenticated user (user access token) based on the OAuth scopes provided. Non-confidential information, such as eBay userID is returned using the default scope. Confidential data for an individual, such as address, email, phone, etc. are returned based on the OAuth scope you use in the call. For business users, all the public business information is returned using the default OAuth scope.

The Identity API can be used to let users log into your app or site using eBay, which frees you from needing to store and protect user's PII (Personal Identifiable Information) data.

Note: All scopes require explicit consent from the user.

Technical overview

The Identity API uses the user resource that returns the account profile information for an authenticated user.

Business use cases

This section outlines the high-level use cases supported by the Identity API.

  • Retrieve the public information of a business using the default scope.
  • Retrieve the public information of an individual using the default scope.
  • Retrieve additional information of an individual using other scopes.

Business Account Response

The business account information is returned when available. This type of account is available only in some countries. For details, see accountType.

Scope

Fields Returned
commerce.identity.readonly
(the default) 
{
  "userId": "007BUS2xyeBay",
  "username": "ebaybusinessuser",
  "accountType": "BUSINESS",
  "registrationMarketplaceId": "EBAY_US",
  "businessAccount": {
    "name": "eBay User",
    "email": "ebaybusinessuser@ebay.com",
    "doingBusinessAs": "Top eBay Seller",
    "primaryPhone": {
      "countryCode": "US",
      "number": "0000000000",
      "phoneType": "MOBILE"
    }
  },
  "address": {
    "addressLine1": "2025 Hamilton Ave",
    "addressLine2": "Apt E 2025",
    "city": "San Jose",
    "stateOrProvince": "CA",
    "postalCode": "95125",
    "country": "US"
  },
  "primaryContact": {
    "firstName": "eBay",
    "lastName": "User"
  }
}

Individual Account Response

In order to protect the user's personal information, the fields returned in the individualAccount container are controlled by the scope. All Partners can use the default scope, which returns the user's public information and their business information if it exists. Access to the other scopes is specified in the Partner's contract with eBay.

The following table shows the fields that are returned in the individualAccount container by scope. For details about these fields, see the getUser method. You can get the information from multiple scopes by specifying all the scopes you're interested in when you generate your token.

Scope

Fields Returned
commerce.identity.readonly
(the default) 
{
  "userId": "007IND2xyeBay",
  "username": "ebayindividualuser",
  "accountType": "INDIVIDUAL",
  "registrationMarketplaceId": "EBAY_US"
}
commerce.identity.status.readonly

This also returns the status field in the business account response. 
{
  "userId": "007IND2xyeBay",
  "username": "ebayindividualuser",
  "status": "CONFIRMED",
  "accountType": "INDIVIDUAL",
  "registrationMarketplaceId": "EBAY_US"
}
commerce.identity.name.readonly 
{
  "userId": "007IND2xyeBay",
  "username": "ebayindividualuser",
  "accountType": "INDIVIDUAL",
  "registrationMarketplaceId": "EBAY_US",
  "individualAccount": {
    "firstName": "eBay",
    "lastName": "User"
  }
}
commerce.identity.address.readonly 
{
  "userId": "007IND2xyeBay",
  "username": "ebayindividualuser",
  "accountType": "INDIVIDUAL",
  "registrationMarketplaceId": "EBAY_US",
  "individualAccount": {
    "registrationAddress": {
      "addressLine1": "2025 Hamilton Ave.",
      "city": "San Jose",
      "stateOrProvince": "CA",
      "postalCode": "95125",
      "country": "US"
    }
  }
}
commerce.identity.email.readonly 
{
  "userId": "007IND2xyeBay",
  "username": "ebayindividualuser",
  "accountType": "INDIVIDUAL",
  "registrationMarketplaceId": "EBAY_US",
  "individualAccount": {
    "email": "ebayindividualuser@ebay.com"
  }
}
commerce.identity.phone.readonly 
{
  "userId": "007IND2xyeBay",
  "username": "ebayindividualuser",
  "accountType": "INDIVIDUAL",
  "registrationMarketplaceId": "EBAY_US",
  "individualAccount": {
    "primaryPhone": {
      "countryCode": "US",
      "number": "0000000000",
      "phoneType": "MOBILE"
    },
    "secondaryPhone": {
      "countryCode": "US",
      "number": "0000000000",
      "phoneType": "MOBILE"
    }
  }
}

API restrictions

Rate limits

The Identity API limits the number of calls that can be made per day on behalf of your application. For the current application rate limits, see the API Call Limits page.

Testing in Sandbox

You can test this API in Sandbox but it will return mock data. Note: You must use the correct scope or scopes for the data you want returned.