API Reference

Profile Endpoint

⚠️ Important Note: Image Accessibility

We do not download or store images on our servers. Therefore, your profile images must be publicly accessible so that our server can retrieve them whenever needed during response generation.

🕒 Important Note: Time Zone

Always return the timeZone field, especially on the persona profile. The Persona reads the current local time from its own profile's timeZone. If it is omitted, the Persona falls back to UTC, producing incorrect time-of-day references (e.g. saying it's 4am when it's 6am locally). See Supported Time Zones.

WEBHOOK · POSThttps://yourdomain.com/your/path

Get a profile by ID.

Parameters

#profileId query · stringrequired

This parameter will contain the profile ID required to retrieve the associated data. Your endpoint must be able to handle this parameter.

Type: string

Responses

#200 Response

Profile data fetched successfully. Your endpoint will respond with the appropriate JSON data.

#application/json

Type: object

#profile objectrequired

Type: object

#id stringrequired

The profile's ID (must be the same as the profileId parameter passed to the endpoint).

Type: string

#gender stringrequired

Gender of the profile owner.

Type: string

Allowed values: "WOMAN", "MAN", "TRANS_MAN", "TRANSMASCULINE", "TRANS_WOMAN", "TRANSFEMININE"

#version string

An arbitrary string compared against the one stored in our profile database; any mismatch will trigger a profile data refresh. For example, you can use the latest update date as the version number.

Type: string

#firstName string

First name of the profile owner. You must provide either a first name or a nickname. At least one is required.

Type: string

#nickname string

Nickname of the profile owner. You must provide either a first name or a nickname. At least one is required.

Type: string

#description string

Description of the profile.

Type: string

#birthdate string

Birthdate of the profile owner, formatted as yyyy-MM-dd.

Type: stringformat: "yyyy-MM-dd"

#countryCode string

Country code of the profile owner. Must be a two-letter ISO 3166-1 alpha-2 code.

Type: stringminLength: 2 maxLength: 2

#city string

City of the profile owner. You must provide a country code for this parameter to be used by our system. If no country code is provided, the city will be ignored.

Type: stringminLength: 0 maxLength: 64

#postalCode string

Postal code of the profile owner. You must provide a country code for this parameter to be used by our system. If no country code is provided, the postal code will be ignored.

Type: stringminLength: 0 maxLength: 64

#timeZone string

Time zone of the profile owner. See our supported time zones list.

Type: string

#features object

Features of the profile.

Type: object

#ethnicity string

The ethnicity of the profile. Default is null.

Type: string

Allowed values: "ASIAN", "BLACK", "CAUCASIAN", "MIDDLE_EAST", "HISPANIC_LATINO", "INDIAN", "MEDITERRANEAN", "OTHER", "UNCERTAIN"

#height integer

Height in metric by default (cm). Set unitSystem to IMPERIAL for inches.

Type: integerformat: "int32"

#weight integer

Weight in metric by default (kg). Set unitSystem to IMPERIAL for pounds.

Type: integerformat: "int32"

#eyesColor string

The color of the eyes. Default is null.

Type: string

Allowed values: "BLACK", "BLUE_GREY", "BLUE", "BROWN", "GREEN_BLUE", "GREEN", "GREY", "OTHER", "UNKNOWN"

#hairColor string

The color of the hair. Default is null.

Type: string

Allowed values: "BLACK", "BLOND", "BROWN", "DARK_BLOND", "GREY", "RED", "WHITE", "OTHER", "UNKNOWN"

#hairLength string

The length of the hair. Default is null.

Type: string

Allowed values: "AVERAGE", "BALD", "HALF_LONG", "LONG", "SHORT", "VERY_LONG", "VERY_SHORT"

#maritalStatus string

The marital status of the profile. Default is null.

Type: string

Allowed values: "SINGLE", "SEPARATED", "IN_RELATIONSHIP", "MARRIED", "DIVORCED", "WIDOW"

#job string

The job of the profile. Default is null.

Type: stringmaxLength: 32

#working boolean

Explicitly controls whether the profile is currently working. When set, this takes precedence over inferring the working status from the presence of the job attribute. Defaults to null, in which case the working status is determined by whether job is set.

Type: booleandefault: null

#interests array

The interests of the profile. Default is an empty array.

Type: array

#Array items

Type: string

Allowed values: "TAILORING", "BOOK_READING", "TRAVELING", "COOKING", "GARDENING", "PHOTOGRAPHY", "PAINTING", "MUSIC", "MOVIES", "CYCLING", "HIKING", "FITNESS", "GAMING", "DANCING", "YOGA", "SOFTWARE_DEVELOPMENT", "DIY_PROJECTS", "WRITING", "LANGUAGES", "ASTRONOMY", "VOLUNTEERING", "FISHING", "BIRD_WATCHING", "SPORTS", "EDUCATION", "ECONOMY", "FOOD_DRINKING", "CULINARY", "TECHNOLOGY", "MEDICAL", "NATURE", "CULTURE", "ART"

#bdsmInterests array

The BDSM interests of the profile. Default is an empty array.

Type: array

#Array items

Type: string

Allowed values: "BDSM_BLOOD_PLAY", "BDSM_BONDAGE", "BDSM_BREATH_PLAY", "BDSM_BUTTOCKS", "BDSM_DOMINATION", "BDSM_EDGE_PLAY", "BDSM_FIRE_PLAY", "BDSM_FISTING", "BDSM_FLOGGING", "BDSM_GOLDEN_SHOWER", "BDSM_HARD", "BDSM_KINKSTER", "BDSM_KNIFE_PLAY", "BDSM_MASOCHIST", "BDSM_NEEDLE_PLAY", "BDSM_ORGASM_DENIAL", "BDSM_PET_PLAY", "BDSM_QUEENING_FACESITTING", "BDSM_SADISM", "BDSM_SOFT", "BDSM_STRAP_ON_DILDO", "BDSM_SUBMISSION", "BDSM_SUSPENSION", "BDSM_ZENTAI"

#sexualInterests array

The sexual interests of the profile. Default is an empty array.

Type: array

#Array items

Type: string

Allowed values: "ANAL", "VAGINAL", "ORAL_GIVING", "ORAL_RECEIVING", "KISSING", "CUDDLING", "DOMINANCE", "SUBMISSION", "BDSM", "ROLEPLAY", "PUBLIC_SEX", "GROUP_SEX", "SWINGING", "WATCHING", "BEING_WATCHED", "THREESOME", "FOREPLAY", "DIRTY_TALK", "SENSUAL_MASSAGE", "TOYS", "LIGHT_BONDAGE", "SPANKING", "CHOKING", "FEET", "EXHIBITIONISM", "VOYEURISM"

#lookingFor array

The profile looking for genders. Default is an empty array.

Type: array

#Array items

Type: string

Allowed values: "MAN", "WOMAN"

#sexualOrientation string

The sexual orientation of the profile. Default is null.

Type: string

Allowed values: "HETEROSEXUAL", "GAY", "LESBIAN", "BISEXUAL", "ASEXUAL", "DEMISEXUAL", "PANSEXUAL", "QUEER", "QUESTIONING", "AROMANTIC", "OMNISEXUAL", "OTHER"

#childrenCount integer

The number of children the profile has. Default is null.

Type: integerformat: "int32"

#wantsChildren string

The preference for having children. Default is null.

Type: string

Allowed values: "YES", "NO", "MAYBE"

#surgeryStatus string

For Transgender profile only. The surgery status of the profile. Default is null.

Type: string

Allowed values: "UNKNOWN", "PRE_OP", "POST_OP", "NON_OP", "PREFER_NOT_TO_SAY"

#unitSystem string

The unit system used for the profile. Default is METRIC.

Type: stringdefault: "METRIC"

Allowed values: "IMPERIAL", "METRIC"

#livingWith string

Describes the user's current living situation. Default is null if unspecified.

Type: string

Allowed values: "ALONE", "KIDS", "PARENTS", "ROOMMATE", "PARTNER", "PARTNER_AND_KIDS"

#education string

The education level of the profile. Default is null.

Type: string

Allowed values: "NO_EDUCATION", "PRIMARY_EDUCATION", "HIGH_SCHOOL_DIPLOMA", "ASSOCIATES_DEGREE", "BACHELORS_DEGREE", "MASTERS_DEGREE", "DOCTORATE"

#religion string

The religion of the profile. Default is null.

Type: string

Allowed values: "NO_RELIGION", "AGNOSTIC", "CHRISTIAN", "CATHOLIC", "PROTESTANT", "MUSLIM", "JEWISH", "HINDU", "BUDDHIST", "SPIRITUAL", "OTHER"

#smoking string

The smoking habits of the profile. Default is null.

Type: string

Allowed values: "NEVER", "OCCASIONALLY", "REGULARLY", "TRYING_TO_QUIT", "VAPING"

#bodyShape string

The body shape of the profile. Default is null.

Type: string

Allowed values: "SLIM", "ATHLETIC", "AVERAGE", "FEW_EXTRA_POUNDS", "CURVY", "FULL_PLUS_SIZE", "MUSCULAR"

#sports array

The sports practiced by the profile. Default is an empty array.

Type: array

#Array items

Type: string

Allowed values: "SOCCER", "BASKETBALL", "TENNIS", "SWIMMING", "RUNNING", "CYCLING", "GYM_CROSSFIT", "YOGA", "MARTIAL_ARTS", "VOLLEYBALL", "GOLF", "SKIING_SNOWBOARDING", "RUGBY", "SURFING"

#musicGenres array

The music genres preferred by the profile. Default is an empty array.

Type: array

#Array items

Type: string

Allowed values: "POP", "ROCK", "HIP_HOP_RAP", "RNB_SOUL", "ELECTRONIC_DANCE", "CLASSICAL", "JAZZ", "COUNTRY", "METAL", "INDIE_FOLK", "LATIN", "REGGAE", "TECHNO"

#personality string

Personality of the profile.

Type: string

Allowed values: "SUPPORTIVE", "TEASING", "CONFIDENT", "GEEKY", "POETIC", "HIGH_ENERGY", "INTELLECTUAL", "ROMANTIC", "SARCASTIC", "POSSESSIVE", "NATURAL", "APPRECIATIVE", "PASSIONATE"

#mainPictureUrl string

URL of the main picture. Must be HTTPS

Type: string

#pictures array

List of public picture URLs. All URLs must be HTTPS

Type: array

#Array items

Type: string

#privatePictures array

List of private picture URLs. All URLs must be HTTPS

Type: array

#Array items

Type: string

#expiresAt string

An ISO-8601 formatted date. By default, set to one week after profile creation. Purges profile data when reached; fresh data is fetched on next use. Avoid setting durations shorter than 24 hours. Use the version parameter for user profile updates.

Type: stringformat: "date-time"

#children array

List of children the profile has.

Type: array

#Array items

Type: object

#name string

Name of the child.

Type: stringminLength: 0 maxLength: 32

#gender string

Gender of the child.

Type: string

Allowed values: "WOMAN", "MAN", "TRANS_MAN", "TRANSMASCULINE", "TRANS_WOMAN", "TRANSFEMININE"

#age integer

Age of the child.

Type: integerformat: "int32"

#pets array

List of pets the profile has.

Type: array

#Array items

Type: object

#name string

Name of the pet.

Type: stringminLength: 0 maxLength: 32

#sex string

Sex of the pet.

Type: string

Allowed values: "MALE", "FEMALE"

#age integer

Age of the pet.

Type: integerformat: "int32"

#breed string

Breed of the pet.

Type: stringminLength: 0 maxLength: 32

#type string

Type of the pet.

Type: stringminLength: 0 maxLength: 32

Illustrative example

{
  "profile": {
    "id": "<string>",
    "gender": "WOMAN",
    "version": "2025-01-01T12:34:20Z",
    "firstName": "<string>",
    "nickname": "<string>",
    "description": "<string>",
    "birthdate": "1990-05-14",
    "countryCode": "FR",
    "city": "<string>",
    "postalCode": "<string>",
    "timeZone": "Europe/Paris",
    "features": {
      "ethnicity": "ASIAN",
      "height": 0,
      "weight": 0,
      "eyesColor": "BLACK",
      "hairColor": "BLACK",
      "hairLength": "AVERAGE",
      "maritalStatus": "SINGLE",
      "job": "<string>",
      "working": null,
      "interests": [
        "TAILORING"
      ],
      "bdsmInterests": [
        "BDSM_BLOOD_PLAY"
      ],
      "sexualInterests": [
        "ANAL"
      ],
      "lookingFor": [
        "MAN"
      ],
      "sexualOrientation": "HETEROSEXUAL",
      "childrenCount": 0,
      "wantsChildren": "YES",
      "surgeryStatus": "UNKNOWN",
      "unitSystem": "METRIC",
      "livingWith": "ALONE",
      "education": "NO_EDUCATION",
      "religion": "NO_RELIGION",
      "smoking": "NEVER",
      "bodyShape": "SLIM",
      "sports": [
        "SOCCER"
      ],
      "musicGenres": [
        "POP"
      ]
    },
    "personality": "SUPPORTIVE",
    "mainPictureUrl": "https://example.org/images/public.jpg",
    "pictures": [
      "https://example.org/images/public.jpg"
    ],
    "privatePictures": [
      "https://example.org/images/private.jpg"
    ],
    "expiresAt": "2025-01-01T12:34:20Z",
    "children": [
      {
        "name": "<string>",
        "gender": "WOMAN",
        "age": 0
      }
    ],
    "pets": [
      {
        "name": "<string>",
        "sex": "MALE",
        "age": 0,
        "breed": "<string>",
        "type": "<string>"
      }
    ]
  }
}