API:2/characters

/v2/characters

HTTP method

GET

Format

json

API version

version 2

Release date

2015-05-22

Scope

account
characters

Optional

none

This resource returns information about characters attached to a specific account.

Parameters

• access_token - (optional) If the API key is not specified in the request header, it can be specified here.

Response

If the endpoint is accessed without any parameters (/v2/characters), it will return an array of characters by name.

Characters can be requested specifically via the ids parameter, or by specifying them percent-encoded in the next URI component. (e.g. /v2/characters/My%20Character)

To retrieve all the characters on an account, pagination can be used. (/v2/characters?ids=all)

By opening the endpoint via /v2/characters/<character name>, a summary of the character information will be given. This is taken from each sub-endpoint listed below. Schema version 2019-12-19T00:00:00.000Z or later, this endpoint will include v2/characters/:id/buildtabs and v2/characters/:id/equipmenttabs and will no longer include v2/characters/:id/skills and v2/characters/:id/specializations

• v2/characters/:id/backstory
• v2/characters/:id/buildtabs
• v2/characters/:id/core
• v2/characters/:id/crafting
• v2/characters/:id/equipment
• v2/characters/:id/equipmenttabs
• v2/characters/:id/inventory
• v2/characters/:id/recipes
• v2/characters/:id/skills
• v2/characters/:id/specializations
• v2/characters/:id/training

The following sub-endpoints are available, but are not included in v2/characters/<character name>:

• v2/characters/:id/buildtabs/active
• v2/characters/:id/equipmenttabs/active
• v2/characters/:id/dungeons
• v2/characters/:id/heropoints
• v2/characters/:id/quests
• v2/characters/:id/sab

There are additionally unique entries such as wvw_abilities, equipment_pvp, build_tabs_unlocked, active_build_tab, equipment_tabs_unlocked, and active_equipment_tab

Backstory

• backstory (array) - An array of strings representing backstory answer IDs pertaining to the questions answered during character creation. References /v2/backstory/answers.

Build Tabs

• build_tabs (array) - An array containing an object for each build tab the character has.
  • tab (number) - The "id" of this tab. (The position at which it resides.)
  • is_active (boolean) - Whether or not this is the tab selected on the character currently.
  • build (object) - Contains detailed information about the build.
    • name (string) - The name given to the build.
    • profession (string) - The characters profession. Resolvable against /v2/professions.
    • specializations (array of objects) - Three objects providing information about the characters selected specializations.
      • id (number) - The specialization id or null if none is selected. Resolvable against /v2/specializations.
      • traits (array of numbers) - Three trait ids or null in places where none is selected. Resolvable against /v2/traits.
    • skills (object) - Contains information about the characters selected skills. All values may be resolved against /v2/skills.
      • heal (number) - The id of the heal skill or null if none is selected.
      • utilities (array of numbers) - Three utility skill ids or null in places where none is selected.
      • elite (number) - The id of the elite skill or null if none is selected.
    • aquatic_skills (object) - Contains information about the characters selected underwater skills. The structure is the same as the one of skills above.
    • legends (array of strings, optional) - Included for revenants only. Two legend ids or null in places where none is selected. Resolvable against /v2/legends.
    • aquatic_legends (array of strings, optional) - Included for revenants only. The structure is the same as the one of legends above.
    • pets (object) (optional) - Included for rangers only. Containers information about the characters selected pets. Resolvable against /v2/pets.
      • terrestrial (array of integers) - Containers the two pet ids the ranger has equipped for terrestrial combat.
      • aquatic (array of integers) - Containers the two pet ids the ranger has equipped for aquaticcombat.

Core

• name (string) - The character's name.
• race (string) - The character's race. Possible values:
  • Asura
  • Charr
  • Human
  • Norn
  • Sylvari
• gender (string) - The character's gender. Possible values:
  • Male
  • Female
• profession (string) - The character's profession. Possible values:
  • Elementalist
  • Engineer
  • Guardian
  • Mesmer
  • Necromancer
  • Ranger
  • Revenant
  • Thief
  • Warrior
• level (integer) - The character's level.
• guild (string, optional) - The guild ID of the character's currently represented guild.
• age (integer) - The amount of seconds this character was played.
• last_modified (string) – An ISO-8601 standard timestamp of when the account information last changed as perceived by the API. This field is only present when a Schema version of 2019-02-21T00:00:00Z or later is requested.
• created (string) - ISO 8601 representation of the character's creation time.
• deaths (integer) - The amount of times this character has been defeated.
• title (number, optional) - The currently selected title for the character. References /v2/titles.

Crafting

• crafting (array) - An array containing an entry for each crafting discipline the character has unlocked
  • discipline (string) - The name of the discipline. Possible values:
    • Armorsmith
    • Artificer
    • Chef
    • Huntsman
    • Jeweler
    • Leatherworker
    • Scribe
    • Tailor
    • Weaponsmith
  • rating (integer) - The current crafting level for the given discipline and character
  • active (boolean - true/false) - Describes if the given discipline is currently active or not on the character.

Equipment

• equipment (array) - An array containing an entry for each piece of equipment currently on the selected character.
  • id (integer) - The item id, resolvable against /v2/items
  • count (integer) (optional) - The unlock count of this item when location is LegendaryArmory. Available on schema 2019-12-19T00:00:00.000Z or later.
  • slot (string) - The equipment slot in which the item is slotted. This value is optional on schema 2019-12-19T00:00:00.000Z or later, will be missing if equipment is in an inactive tab. Possible values:
    • HelmAquatic
    • Backpack
    • Coat
    • Boots
    • Gloves
    • Helm
    • Leggings
    • Shoulders
    • Accessory1
    • Accessory2
    • Ring1
    • Ring2
    • Amulet
    • WeaponAquaticA
    • WeaponAquaticB
    • WeaponA1
    • WeaponA2
    • WeaponB1
    • WeaponB2
    • Sickle
    • Axe
    • Pick
    • FishingRod
    • FishingLure
    • PowerCore
    • SensoryArray
    • Relic
  • infusions (array) (optional) - returns an array of infusion item ids which can be resolved against /v2/items
  • upgrades (array) (optional) - returns an array of upgrade component item ids which can be resolved against /v2/items
  • skin (integer) (optional) - Skin id for the given equipment piece. Can be resolved against /v2/skins
  • stats (object) (optional) - Contains information on the stats chosen if the item offers an option for stats/prefix.
    • id (integer) - The itemstat id, can be resolved against /v2/itemstats
    • attributes (object) - Contains a summary of the stats on the item.
      • Power (integer) (optional) - Shows the amount of power given
      • Precision (integer) (optional) - Shows the amount of Precision given
      • Toughness (integer) (optional) - Shows the amount of Toughness given
      • Vitality (integer) (optional) - Shows the amount of Vitality given
      • Condition Damage (integer) (optional) - Shows the amount of Condition Damage given
      • Condition Duration (integer) (optional) - Shows the amount of Condition Duration given
      • Healing (integer) (optional) - Shows the amount of Healing Power given
      • BoonDuration (integer) (optional) - Shows the amount of Boon Duration given
  • binding (string) (optional) - describes which kind of binding the item has. Possible values:
    • Character
    • Account
  • location (string) - describes where this item is stored. Available on schema 2019-12-19T00:00:00.000Z or later. Possible values:
    • Equipped - equipped in the active tab.
    • Armory - equipped in an inactive tabs.
    • EquippedFromLegendaryArmory - if the item is stored in the account-wide legendary armory, but equipped in the active tab.
    • LegendaryArmory - if the item is stored in the account-wide legendary armory, but equipped in an inactive tabs.
  • tabs (array of numbers) - identifies which tabs this particular item is reused in. Available on schema 2019-12-19T00:00:00.000Z or later.
  • charges (number) (optional) - The amount of charges remaining on the item.
  • bound_to (string) (optional, only if character bound) - Name of the character the item is bound to.
  • dyes (array of numbers) - Array of selected dyes for the equipment piece. Values default to null if no dye is selected. Colors can be resolved against v2/colors

Equipment Tabs

• equipment_tabs (array) - An array containing an object for each equipment tab the character has.
  • tab (number) - The "id" of this tab. (The position at which it resides.)
  • name (string) - The name given to the equipment combination.
  • is_active (boolean) - Whether or not this is the tab selected on the character currently.
  • equipment (array of objects) - Contains an object for each equiped piece of equipment.
    • id (number) - The item id of the equipment piece. Resolvable against /v2/items.
    • slot (string) - In which slot the equipment piece is equiped. Possible values:
      • Helm
      • Shoulders
      • Coat
      • Gloves
      • Leggings
      • Boots
      • WeaponA1
      • WeaponA2
      • WeaponB1
      • WeaponB2
      • Backpack
      • Accessory1
      • Accessory2
      • Amulet
      • Ring1
      • Ring2
      • HelmAquatic
      • WeaponAquaticA
      • WeaponAquaticB
    • skin (number, optional) - The skin id of the skin transmuted onto the equipment piece. Resolvable against /v2/skins.
    • upgrades (array of numbers, optional) - The item ids of the upgrade components sloted in the weapon. Resolvable against /v2/items.
    • infusions (array of numbers, optional) - The item ids of the infusions sloted in the weapon. Resolvable against /v2/items.
    • binding (string, optional) - The binding of the item. Possible values:
      • Account
      • Character
    • bound_to (string, optional) - The name of the character to which the item is bound.
    • location (string) - Either Equipped or Armory.
    • dyes (array of numbers, optional) - Four dye ids representing the dyes used in the dye slots of the equipment piece or null if a dye slot is unavailable for a piece. Resolvable against /v2/colors.
    • stats (object, optional) - Contains detailed information on the weapon stats.
      • id (number) - The id of the wepons stats. Resolvable against /v2/itemstats.
      • attributes (object) - Contains the weapon attributes in the form of key value pairs with the key being the attribute name and the value itself.
  • equipment_pvp (object) - Contains the following key-value pairs:
    • amulet (number) - resolve id against v2/pvp/amulets.
    • rune (number) - resolve id against v2/items.
    • sigils (array of numbers) - resolve ids against v2/items. Will contain nulls for unequipped items.
      • Sigils are provided in the order [<primary weapon sigil 1>, <secondary weapon sigil 1>, <primary weapon sigil 2>, <secondary weapon sigil 2>].

Heropoints

Returns an array of strings marking each hero point obtained by the character. Can be checked against skill_challenges in /v2/continents maps.

Inventory

• bags (array) - Contains one object structure per bag in the character's inventory
  • id (integer) - The bag's item id which can be resolved against /v2/items
  • size (integer) - The amount of slots available with this bag.
  • inventory (array) - Contains one object structure per item, object is null if no item is in the given bag slot.
    • id (integer) - The item id which can be resolved against /v2/items
    • count (integer) - Amount of item in the stack. Minium of 1, maximum of 250.
    • charges (integer) (optional) - The number of charges on an item.
    • infusions (array) (optional) - returns an array of infusion item ids which can be resolved against /v2/items
    • upgrades (array) (optional) - returns an array of upgrade component item ids which can be resolved against /v2/items
    • skin (integer) (optional) - Skin id for the given equipment piece. Can be resolved against /v2/skins
    • stats (object) (optional) - Contains information on the stats chosen if the item offers an option for stats/prefix.
      • id (integer) - The itemstat id, can be resolved against /v2/itemstats.
      • attributes (object) - Contains a summary of the stats on the item.
        • Power (integer) (optional) - Shows the amount of power given
        • Precision (integer) (optional) - Shows the amount of Precision given
        • Toughness (integer) (optional) - Shows the amount of Toughness given
        • Vitality (integer) (optional) - Shows the amount of Vitality given
        • Condition Damage (integer) (optional) - Shows the amount of Condition Damage given
        • Condition Duration (integer) (optional) - Shows the amount of Condition Duration given
        • Healing (integer) (optional) - Shows the amount of Healing Power given
        • BoonDuration (integer) (optional) - Shows the amount of Boon Duration given
    • dyes (array of numbers) (optional) - Array of selected dyes for the equipment piece. Values default to null if no dye is selected. Colors can be resolved against v2/colors
    • binding (string) (optional) - describes which kind of binding the item has. Possible values:
      • Character
      • Account
    • bound_to (string) (optional, only if character bound) - Name of the character the item is bound to.

Skills

• skills (object) - contains the pve, pvp, and wvw objects for the current utilities equipped.
  • pve (object) - contains the information on each slotted utility for PvE
    • heal (integer) - contains the skill id for the heal skill, resolvable against /v2/skills.
    • utilities (array of integers) - each integer corresponds to a skill id for the equipped utilities, resolvable against /v2/skills.
    • elite (integer) - contains the skill id for the elite skill, resolvable against /v2/skills.
    • legends (array of strings) (Revenant only) - each string corresponds to a Revenant legend, resolvable against /v2/legends.
  • pvp (object) - contains the information on each slotted utility for PvP
    • heal (integer) - contains the skill id for the heal skill, resolvable against /v2/skills.
    • utilities (array of integers) - each integer corresponds to a skill id for the equipped utilities, resolvable against /v2/skills.
    • elite (integer) - contains the skill id for the elite skill, resolvable against /v2/skills.
    • legends (array of strings) (Revenant only) - each string corresponds to a Revenant legend, resolvable against /v2/legends.
  • wvw (object) - contains the information on each slotted utility for WvW
    • heal (integer) - contains the skill id for the heal skill, resolvable against /v2/skills.
    • utilities (array of integers) - each integer corresponds to a skill id for the equipped utilities, resolvable against /v2/skills.
    • elite (integer) - contains the skill id for the elite skill, resolvable against /v2/skills.
    • legends (array of strings) (Revenant only) - each string corresponds to a Revenant legend, resolvable against /v2/legends.

Specialization

• specializations (object) - contains the pve, pvp, and wvw objects for the current specializations and traits equipped.
  • pve (array) - contains the information on each slotted specialization and trait for PvE
    • id (integer) - Specialization id, can be resolved against /v2/specializations.
    • traits (array of integers) - returns ids for each selected trait, can be resolved against /v2/traits.
  • pvp (array) - contains the information on each slotted specialization and trait for PvP
    • id (integer) - Specialization id, can be resolved against /v2/specializations.
    • traits (array of integers) - returns ids for each selected trait, can be resolved against /v2/traits.
  • wvw (array) - contains the information on each slotted specialization and trait for WvW
    • id (integer) - Specialization id, can be resolved against /v2/specializations.
    • traits (array of integers) - returns ids for each selected trait, can be resolved against /v2/traits.

Training

• training (array) - contains objects for each skill tree trained
  • id (integer) - Skill tree id, can be compared against the training section for each /v2/professions.
  • spent (integer) - Shows how many hero points have been spent in this tree
  • done (boolean - true/false) - States whether or not the tree is fully trained.

Super Adventure Box (sab)

• zones (array) - Contains objects describing which worlds, and in which difficult, have been cleared
  • id (integer) - The world id
  • mode (string) - The difficulty mode cleared
  • world (integer) - The world number
  • zone (integer) - The zone number
• unlocks (array) - Contains objects describing the unlocks on the given character. (list of possible values visible on [1]
  • id (integer) - The id of the unlock
  • name (string) - The name of the upgrade
• songs (array) - Contains the objects of unlocked songs on the character
  • id (integer) - The id of the song
  • name (string) - The name of the song

Extras

• wvw_abilities (array) - contains information on each trained wvw ability
  • id (integer) - ability id, can be resolved against /v2/wvw/abilities
  • rank (integer) - current rank for the given ability.

• equipment_pvp (object) - Contains information on character's pvp equipment setup.
  • amulet (integer) - Id for the equipped pvp amulet, can be resolved against /v2/pvp/amulets.
  • rune (integer) - Id for the equipped pvp rune, can be resolved against /v2/items.
  • sigils (array of integers) - Returns the id for all equipped pvp sigils. Can be resolved against /v2/items.
• flags (array of strings) - Returns character flags. Possible values:
  • Beta - Beta character for testing period of add-ons

The following fields are available on schema version 2019-12-19T00:00:00.000Z or later.

• build_tabs_unlocked (integer) - Number of build tabs unlocked for this character.
• active_build_tab (integer) - Tab id of currently active build.
• equipment_tabs_unlocked (integer) - Number of equipment tabs unlocked for this character.
• active_equipment_tab (integer) - Tab id of currently active equipment.

Examples

Request

 https://api.guildwars2.com/v2/characters/<character name>/<additional endpoint>
 Authorization: Bearer <API key>

 https://api.guildwars2.com/v2/characters/<character name>/<additional endpoint>?access_token=<API key>

Backstory

 {
   "backstory": [
       "7-54",
       "12-75",
       "186-162",
       "11-72",
       "10-67"
   ]
 }

Core

 {
   "name": "<character name>",
   "race": "Asura",
   "gender": "Male",
   "profession": "Elementalist",
   "level": 80,
   "guild": "<guild id>",
   "age": 12631700,
   "created": "2013-04-27T04:15:00Z",
   "deaths": 9193,
   "title": 251
 }

Crafting

 {
   "crafting": [
       {
           "discipline": "Artificer",
           "rating": 500,
           "active": true
       },
       {
           "discipline": "Huntsman",
           "rating": 12,
           "active": false
       },
       {
           "discipline": "Jeweler",
           "rating": 136,
           "active": false
       },
       {
           "discipline": "Tailor",
           "rating": 500,
           "active": true
       }
   ]
 }

Equipment

 {
   "equipment": [
       {
           "id": 47874,
           "slot": "HelmAquatic",
           "upgrades": [
               24836
           ],
           "binding": "Character",
           "bound_to": "<Character name>"
       },
       {
           "id": 72309,
           "slot": "Backpack",
           "infusions": [
               77310,
               49433
           ],
           "skin": 6561,
           "stats": {
               "id": 584,
               "attributes": {
                   "Power": 63,
                   "Precision": 40,
                   "CritDamage": 40
               }
           },
           "binding": "Account"
       },
       {
           "id": 48079,
           "slot": "Coat",
           "upgrades": [
               24836
           ],
           "infusions": [
               49432
           ],
           "skin": 5719,
           "binding": "Account"
       },
       {...},
       {
           "id": 22997,
           "slot": "Sickle",
           "binding": "Account",
           "charges": 31
       },
       {
           "id": 23000,
           "slot": "Axe",
           "binding": "Account",
           "charges": 7
       },
       {
           "id": 48933,
           "slot": "Pick",
           "binding": "Account"
       }
   ]
 }

Heropoints

 [
   "0-0",
   "0-2",
   ...,
   "0-247",
   "0-248"
 ]

Inventory

 {
   "bags": [
       {
           "id": 38013,
           "size": 20,
           "inventory": [
               {
                   "id": 76072,
                   "count": 1,
                   "binding": "Character",
                   "bound_to": "<Character name>"
               },
               {...},
               {
                   "id": 43451,
                   "count": 11
               }
           ]
       },
       {...},
       {
           "id": 67518,
           "size": 20,
           "inventory": [
               {...},
               {
                   "id": 849,
                   "count": 1
               },
               null,
               null,
               null,
               null,
               null,
               null
           ]
       }
   ]
 }

Skills

 {
   "skills": {
       "pve": {
           "heal": 29535,
           "utilities": [
               5734,
               5567,
               5542
           ],
           "elite": 29968
       },
       "pvp": {
           "heal": 29535,
           "utilities": [
               30432,
               30662,
               29948
           ],
           "elite": 29968
       },
       "wvw": {
           "heal": 29535,
           "utilities": [
               5734,
               5536,
               5542
           ],
           "elite": 29968
       }
   }
 }

Specialization

 {
   "specializations": {
       "pve": [
           {
               "id": 31,
               "traits": [
                   296,
                   325,
                   1510
               ]
           },
           {...},
           {
               "id": 48,
               "traits": [
                   1952,
                   2015,
                   1986
               ]
           }
       ],
       "pvp": [...],
       "wvw": [...]
   }
 }

Training

 {
   "training": [
       {
           "id": 33,
           "spent": 22,
           "done": true
       },
       {...},
       {
           "id": 31,
           "spent": 250,
           "done": true
       }
   ]
 }

Sab

 {
   "zones": [
       {
           "id": 1,
           "mode": "normal",
           "world": 1,
           "zone": 1
       },
       ...
       {
           "id": 13,
           "mode": "infantile",
           "world": 1,
           "zone": 1
       },
       ...
       {
           "id": 25,
           "mode": "tribulation",
           "world": 1,
           "zone": 1
       },
       ...
   ],
   "unlocks": [
       {
           "id": 1,
           "name": "chain_stick"
       },
       ...
   ],
   "songs": [
       {
           "id": 1,
           "name": "secret_song"
       },
       ...
   ]
 }

Overview

 {
   "name": "<character name>",
   "race": "Asura",
   "gender": "Male",
   "profession": "Elementalist",
   "level": 80,
   "guild": "<guild id>",
   "age": 12631700,
   "created": "2013-04-27T04:15:00Z",
   "deaths": 9193,
   "crafting": [...],
   "title": 251,
   "backstory": [...],
   "wvw_abilities": [
       {
           "id": 14,
           "rank": 4
       },
       {...},
       {
           "id": 2,
           "rank": 4
       }
   ],
   "specializations": {...},
   "skills": {...},
   "equipment": [...],
   "recipes": [
       1,
       2,
       ...,
       11878,
       11887
   ],
   "equipment_pvp": {
       "amulet": 29,
       "rune": 21212,
       "sigils": [
           21154,
           65230,
           21152,
           21124
       ]
   },
   "training": [...],
   "bags": [...]
 }

---

API

Account

achievements • bank • build storage • daily crafting • dungeons • dyes • finishers • gliders • home instance (cats • nodes) • homestead (decorations • glyphs) • legendary armory • luck • mail carriers • map chests • masteries • mastery/points • materials • minis • mounts (types • skins) • novelties • outfits • progression • PvP heroes • raids • recipes • shared inventory • jade bots • skiffs • skins • titles • wallet • wizard's vault (listings • daily • weekly • special) • world bosses

Achievements

achievements • categories • daily (tomorrow) • groups

Characters

backstory • build tabs • core • crafting • equipment • equipment tabs • hero points • inventory • quests • recipes • Super Adventure Box • skills • specializations • training

Daily Rewards

daily crafting • map chests • world bosses

Events

event details^v1

Game mechanics

colors • currencies • dungeons • emotes • legends • legendary armory • masteries • pets • professions • races • raids • skills • specializations • titles • traits

Guild

emblem (backgrounds • foregrounds) • info (log • members • ranks • stash • storage • teams • treasury • upgrades) • permissions • search • upgrades

Home instance

cats • nodes

Homestead

decorations • categories • glyphs

Items

items • item stats • materials • recipes (search)

Maps

continents • maps

Story

backstory (answers • questions) • quests • stories (seasons)

Structured PvP

amulets • games • heroes • ranks • seasons (leaderboards) • standings • stats

Commerce (Trading post)

delivery • exchange • listings • prices • transactions

Wardrobe

finishers • gliders • jade bots • mail carriers • minis • mounts (skins • types) • novelties • outfits • skiffs • skins

Wizard's Vault

listings • objectives

World vs. World

abilities • matches (guild stats • match stats • overview • scores ^[?] • team stats) • objectives • ranks • upgrades • worlds

Miscellaneous

build • create subtoken • files • quaggans • token info

Additional services

assets • render • tiles

Help topics

Best practices • Maps • Mumble Link