REST API

Overview

The Gravatar Public API allows developers to retrieve Gravatar profile information. This documentation will help you understand how to integrate with the API to perform operations related to user profiles.

To create an application and API key, visit the Gravatar Developer Dashboard.

Creating an API key

You can create the API Key as follows:

1. Login in to your Gravatar account (or the Gravatar account you want to use to generate the key)
2. Navigate to the developers portal
3. Tap on Create new Application
4. Fill the required data and follow the flow

Base URL

All API requests are made to the following base URL:

https://api.gravatar.com/v3

Rate Limits

Unauthenticated requests are limited to 100 per hour.

Authenticated requests are limited to 1000 per hour.

You will see error code 429 for too many requests.

If you reach this limit and your application needs higher limits, please contact us here.

Authentication

Some endpoints require authentication. The API uses Bearer tokens to authenticate requests, which should be included in the Authorization header of the request.

To get an API Key for authorization, visit the Gravatar Developer Dashboard.

Using an API key is always recommended, and will give you:

• Higher rate limits (1000 vs 100 requests per hour)
• Access to additional endpoints, including
  • Links,
  • Registration and last edit timestamps,
  • Contact info,
  • Payment and wallet info,
  • and Gallery images

API Methods

Get Profile by Identifier

Retrieve a user’s profile by an identifier such as the SHA256 hash of an email address or a profile URL slug.

• URL: /profiles/{profileIdentifier}
• Method: GET
• URL Parameters:
  • profileIdentifier [required]: The identifier for the profile, which can be a SHA256 hash of the email or a Gravatar profile URL slug (ie. gravatar.com/slug).
• Headers:
  • Authorization [optional]: Bearer token for authenticated requests.
• Success Response:
  • Code: 200 OK
  • Content: A JSON object containing the user’s profile details.
• Error Responses:
  • Code: 404 Not Found – No profile found for the given identifier.
  • Code: 429 Too Many Requests – API rate limit exceeded.
  • Code: 500 Internal Server Error – An error occurred on the server.
• Sample Call:

curl -X GET "https://api.gravatar.com/v3/profiles/{profileIdentifier}" -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

• Notes:
  • Full profile information is available only in authenticated requests.

Schemas

Profile

Describes a user’s profile information.

Properties:

hash: The SHA256 hash of the user’s primary email address.
Example: "31c5543c1734d25c7206f5fd591525d0295bec6fe84ff82f946a34fe970a1e66"

display_name: The user’s display name that appears on their profile.
Example: "Alex Morgan"

profile_url: The full URL to the user’s Gravatar profile.
Example: "https://gravatar.com/example"

avatar_url: The URL to the user’s avatar image, if set.
Example: "https://0.gravatar.com/avatar/33252cd1f33526af53580fcb1736172f06e6716f32afdd1be19ec3096d15dea5"

avatar_alt_text: Alternative text describing the user’s avatar.
Example: "Alex Morgan's avatar image. Alex is smiling and standing beside a large dog who is looking up at Alex."

location: The user’s geographical location.
Example: "New York, USA"

description: A short biography or description about the user found on their profile.
Example: "I like playing hide and seek."

job_title: The user’s current job title.
Example: "Landscape Architect"

company: The name of the company where the user is employed.
Example: "ACME Corp"

verified_accounts: An array of verified accounts the user has added to their profile. The number of verified accounts displayed is limited to a maximum of 4 in unauthenticated requests.

pronunciation: A phonetic guide to pronouncing the user’s name.
Example: "Al-ex Mor-gan"

pronouns: The pronouns the user prefers to use.
Example: "She/They"

number_verified_accounts: The total number of verified accounts the user has added to their profile, including those not displayed on their profile. This property is only provided in authenticated API requests.
Example: 3

last_profile_edit: The date and time (UTC) when the user last edited their profile. This property is only provided in authenticated API requests.
Example: "2021-10-01T12:00:00Z"

registration_date: The date the user registered their account. This property is only provided in authenticated API requests.
Example: "2021-10-01"

Links

Represents a link the user has added to their profile.

This property is only provided in authenticated API requests.

• Properties:
  • label: The label for the link.
  • url: The URL to the link.

Example

{
  "label": "Personal Website",
  "url": "https://example.com"
}

CryptoWalletAddress

Represents a cryptocurrency wallet address.

• Properties:
  • label: The label for the cryptocurrency.
  • address: The cryptocurrency wallet address.

Example

{
  "label": "ETH",
  "address": "0xABC123..."
}

VerifiedAccount

Represents a verified account on a user’s profile.

The number of verified accounts displayed is limited to a maximum of 4 in unauthenticated requests.

• Properties:
  • service_label: The name of the service.
  • service_icon: The URL to the service’s icon.
  • url: The URL to the user’s profile on the service.

Example

{
  "service_label": "Tumblr",
  "service_icon": "https://gravatar.com/icons/tumblr-alt.svg",
  "url": "https://example.tumblr.com/"
}

Contact Info

The user’s public contact information.

This property is only provided in authenticated API requests.

• Properties:
  • home_phone, work_phone, cell_phone, email, contact_form, calendar.

Example

{
  "home_phone": "+1-555-555-0100",
  "work_phone": "+1-555-555-0101",
  "cell_phone": "+1-555-555-0102",
  "email": "alex@example.com",
  "contact_form": "https://example.com/contact-me",
  "calendar": "https://example.com/calendar"
}

Payments

Details the payment methods and links provided by the user.

Payments are only provided in authenticated API requests.

• Properties:
  • links: An array of payment URLs the user has added to their profile.
  • crypto_wallets: An array of cryptocurrency addresses the user accepts.

Example

{
  "links": [
    {
      "label": "Donations",
      "url": "https://example.com/donate"
    }
  ],
  "crypto_wallets": [
    {
      "label": "BTC",
      "address": "1BoatSLRHtKNngkdXEeobR76b53LETtpyT"
    }
  ]
}

GalleryImage

Represents a gallery image a user has uploaded.

This property is only provided in authenticated API requests.

• Properties:
  • url: The URL to the image.

Example

{
  "url": "https://0.gravatar.com/userimage/5/04bbd674f72c703f6335e2e7a00acc9a"
}

Versioning

This API adheres to semantic versioning. The current version is 3.0.0.