FF Web API Documentation

Addresses

Production URL:

Beta URL:

Submit your IP whitlisting requests to the FF Game Reliability Engineering Team for access.

Responses

All response bodies are in JSON format. A response will have status code 200 if and only if the API call succeeds.

The API supports gzip compression. Set Accept-Encoding: gzip in request headers in order to get response bodies compressed.

Error Responses

Error responses are guaranteed to have 4** or 5** status codes and an error key in the response body:

{
    "error": "Error reason"
}

Common error status codes include:

APIs With Hard QPS Limits

Call these APIs as rare as possible.

They interact directly with master databases. Calling these APIs too frequently can bring down the whole FF game, thus hard QPS limits are applied.

Add or Remove Items, Coins & Gems from an Account

Request

{
    "account_id": "41000862",
    "data": {
        "add_item_list":[{"id": 400000433, "cnt": 1}],
        "del_item_list":[{"id": 400000429, "cnt": 1}],
        "coins_delta": 100,
        "gems_delta": -200
    },
    "lock_region": "TW"
}

Response

{
    "trans_id": "1232167213788749824"
}

Send Mails

Request

{
    "account_id": "41000380",
    "lock_region": "TW",
    "mail_info": [
        {
            "title": "mail title",
            "content": "mail content",
            "source": 1,
            "action_type": 0,
            "attachment": {
                "rewards": {
                    "items": [
                        {
                            "id": 400000433,
                            "cnt": 10
                        }
                    ],
                    "coins": 100,
                    "gems": 100
                }
            }
        }
    ]
}

mail_info.source:

mail_info.action_type:

The game client won’t display more than 5 mail attachments.

Response

{}

Batch Send Mails

Request

{
    "account_regions": [
        {
            "account_id": "41000380",
            "lock_region": "TW"
        }
    ],
    "mail_info": [
        {
            "title": "mail title",
            "content": "mail content",
            "source": 1,
            "action_type": 0,
            "attachment": {
                "rewards": {
                    "items": [
                        {
                            "id": 400000433,
                            "cnt": 10
                        }
                    ],
                    "coins": 100,
                    "gems": 100
                }
            }
        }
    ]
}

The account_regions list length is limited to 30.

mail_info.source:

mail_info.action_type:

The game client won’t display more than 5 mail attachments.

Response

{}

APIs Without QPS Limit

These APIs interact with replica databases. They are capable of handling more frequent requests.

Get Account Info

By Open ID

By Account ID

By Nickname

Response

{
    "account_id": "41000380",
    "external_id": "3f12105951852e1e5637d833ca104f93",
    "external_type": 3,
    "nickname": "apm1467",
    "region": "TW",
    "lock_region_time": 1574850719,
    "reg_avatar": 0,
    "external_uid": "2408315505894765"
}

Get Account Wallet

Request

?account_id=41000380

or

{"account_id": "41000380"}

Response

{
    "account_id": "41000380",
    "wallet": {
        "coins": 0,
        "gems": 164638
    }
}

Check Account Permanently Owned Items

This API returns the item IDs of permanently owned items of the player. Use this API to check if certain unique items are owned by the player.

Request

{
    "account_id": "41000380",
    "item_id_list": [
        101000000,
        101000005,
        101000006
    ]
}

If item_id_list is empty, the API will return the item IDs of all permanently owned items of the player.

If item_id_list is not empty, only the item IDs in this list will be checked. You can submit just the item IDs you want to check, so the API responses can be faster. The list length is limited to 30.

Response

{
    "account_id": "41000380",
    "permanently_owned": [
        101000005,
        101000006
    ]
}

Get Account Backpack

This API is slower than “Check Account Permanently Owned Items”.

Request

{
    "account_id": 41000380,
    "item_id_list": [
        101000000,
        101000005
    ]
}

If item_id_list is empty, the API will return all items owned by the player.

If item_id_list is not empty, only the items in this list will be returned. You can submit just the item IDs you want to check, so the API responses can be faster. The list length is limited to 30.

Response

{
    "account_id": "41000380",
    "backpack": [
        {
            "id": 101000005,
            "cnt": 1,
            "left_use_times": -1,
            "history_owned_cnt": 1,
            "item_status": 1
        }
    ]
}

backpack.item_status:

backpack.cnt is guaranteed to be positive (non-zero).

Check Account EP Badges

Request

?account_id=41000665&ep_id=19

or

{"account_id": "41000665", "ep_id": 19}

Response

{
    "account_id": "41000665",
    "ep_id": 19,
    "owned_pass": true,
    "badge_count": 125,
    "epid_preorder": 0
}

epid_preorder is the ID of the Elite Pass the player has preordered.

Get Match Stats List

By Account ID

By Match ID

Response

{
    "data": [
        {
            "match_id": "1215211969942966272",
            "account_id": "41000959",
            "create_time": 1578564091,
            "end_time": 1578564110,
            "match_stats": {
                "account_id": "41000959",
                "group_id": "41000959",
                "survival_time": 0,
                "rank": 50,
                "kills": 0,
                "damage": 0,
                "moving_distance": 0,
                "revival_count": 0,
                "vehicle_kills": 0,
                "headshot_count": 0,
                "headshot_kills": 0,
                "knockdown_count": 0,
                "pickup_count": 0,
                "assists": 0,
                "is_survive": true,
                "out_index": 1,
                "ranking_points": 1000,
                "killer": {
                    "account_id": "0",
                    "ranking_points": 0,
                    "dead_order": 0
                },
                "killed_players": [],
                "down_count": 0,
                "achievements": [],
                "kill_bots": 0,
                "enable_achievements": true,
                "avatar_id": 102000004,
                "teammates": [],
                "avg_ranking_points": 1000,
                "fratricide_damage": 0,
                "direct_kills": 0,
                "group_mode": 0,
                "match_mode": 1,
                "player_count": 50,
                "banner_id": 0,
                "head_pic": 0,
                "clan_name": "",
                "level": 1,
                "season_rank": 1,
                "game_mode": 1,
                "map_id": 1,
                "has_elite_pass": false,
                "badge_id": 1001000021,
                "badge_cnt": 0,
                "clothes_id": [
                    209000001,
                    203000573,
                    208000000,
                    204000345,
                    211000000,
                    205000299
                ],
                "real_group_id": "0",
                "ep_goldlimit_bonus": 100,
                "liked": 0,
                "real_player_rank": 1,
                "real_player_count": 1,
                "show_rank": true,
                "use_red_envelope": [],
                "received_red_envelope": [],
                "pet_id": 0,
                "pet_name": "",
                "ingame_items": [],
                "difficulty": 0,
                "ai_type": 0,
                "pve_primary_weapon_skin": 0,
                "pet_skin_id": 0,
                "used_revive_tokens": {
                    "used_gems": 0,
                    "used_coins": 0,
                    "used_items": []
                },
                "hack_reason": 0,
                "sit_on_throne": false,
                "wta_curr_type": 0,
                "warm_game": {
                    "type": 0,
                    "level": 0
                },
                "role": 0,
                "championship_type": 1,
                "linkage_info": {
                    "type": 0,
                    "pirate_map_token_id": 0
                },
                "revenge_success_times": 0
            },
            "income": {
                "exp": 0,
                "coins": 0,
                "rank_points": 0,
                "kill_points": 0,
                "damage_points": 0,
                "level_before": 0,
                "level_after": 0,
                "exp_before": 0,
                "exp_after": 0,
                "coins_before": 0,
                "coins_after": 0,
                "coins_gained_today": 0,
                "coins_gain_limit": 0,
                "mmr_delta": 0,
                "ranking_points_delta": 0,
                "ranking_points_before": 0,
                "ranking_points_after": 0,
                "level_rewards": {
                    "items": [],
                    "coins": 0,
                    "gems": 0,
                    "exps": 0,
                    "activeness": 0
                },
                "daily_reward_exp": 0,
                "daily_reward_coins": 0,
                "rank_before": 0,
                "rank_after": 0,
                "has_rank_upgrade_rewards": false,
                "is_rank": false,
                "is_logout_match": true,
                "honor_point_delta": 0,
                "game_drops": [],
                "is_loss_prevented": false,
                "coin_limit_event_bonus": 0,
                "debris_limit_event_bonus": 0,
                "ranking_points_detail": {
                    "ranking_score": 0,
                    "battle_score": 0,
                    "newbie_score": 0,
                    "victory_score": 0,
                    "first_win_score": 0,
                    "chicken_protect": false,
                    "birth_island_quit_score": 0,
                    "scale_ranking_score": 0,
                    "scale_battle_score": 0
                },
                "race_point_delta": 0,
                "ranking_token_id": 0,
                "ranking_token_delta": 0,
                "ranking_token_num": 0,
                "coins_detail": {
                    "coin_match": 0,
                    "coin_clan_buff": 0,
                    "coin_event_bonus": 0,
                    "coin_card": 0,
                    "coin_ranking": 0,
                    "coin_championship": 0
                },
                "exp_detail": {
                    "exp_match": 0,
                    "exp_clan_buff": 0,
                    "exp_event_bonus": 0,
                    "exp_card": 0,
                    "exp_ranking": 0,
                    "exp_championship": 0
                },
                "pet_exp_detail": {
                    "id": 0,
                    "name": "",
                    "level_before": 0,
                    "level_after": 0,
                    "exp_before": 0,
                    "exp_after": 0,
                    "skin_id": 0
                },
                "debris_detail": [],
                "ingame_items": [],
                "ranking_token_max": 0,
                "is_double_ranking_point_activity": false,
                "is_double_token_activity": false,
                "double_ranking_point_card_id": 0,
                "chip_num": 0,
                "no_deduct_card_id": 0,
                "is_championship": false,
                "pirate_map_award_id": 0,
                "mmr_after": 0
            }
        }
    ]
}

Only match stats of the latest 14 days are available.

data.match_stats.match_mode:

data.match_stats.group_mode:

data.match_stats.game_mode:

Get Single Match Stats

Request

{
    "match_id": "1215211969942966272",
    "account_id": "41000959",
    "lock_region": "TW"
}

Response

{
    "match_id": "1215211969942966272",
    "account_id": "41000959",
    "create_time": 1578564091,
    "end_time": 1578564110,
    "match_stats": {
        "account_id": "41000959",
        "group_id": "41000959",
        "survival_time": 0,
        "rank": 50,
        "kills": 0,
        "damage": 0,
        "moving_distance": 0,
        "revival_count": 0,
        "vehicle_kills": 0,
        "headshot_count": 0,
        "headshot_kills": 0,
        "knockdown_count": 0,
        "pickup_count": 0,
        "assists": 0,
        "is_survive": true,
        "out_index": 1,
        "ranking_points": 1000,
        "killer": {
            "account_id": "0",
            "ranking_points": 0,
            "dead_order": 0
        },
        "killed_players": [],
        "down_count": 0,
        "achievements": [],
        "kill_bots": 0,
        "enable_achievements": true,
        "avatar_id": 102000004,
        "teammates": [],
        "avg_ranking_points": 1000,
        "fratricide_damage": 0,
        "direct_kills": 0,
        "group_mode": 0,
        "match_mode": 1,
        "player_count": 50,
        "banner_id": 0,
        "head_pic": 0,
        "clan_name": "",
        "level": 1,
        "season_rank": 1,
        "game_mode": 1,
        "map_id": 1,
        "has_elite_pass": false,
        "badge_id": 1001000021,
        "badge_cnt": 0,
        "clothes_id": [
            209000001,
            203000573,
            208000000,
            204000345,
            211000000,
            205000299
        ],
        "real_group_id": "0",
        "ep_goldlimit_bonus": 100,
        "liked": 0,
        "real_player_rank": 1,
        "real_player_count": 1,
        "show_rank": true,
        "use_red_envelope": [],
        "received_red_envelope": [],
        "pet_id": 0,
        "pet_name": "",
        "ingame_items": [],
        "difficulty": 0,
        "ai_type": 0,
        "pve_primary_weapon_skin": 0,
        "pet_skin_id": 0,
        "used_revive_tokens": {
            "used_gems": 0,
            "used_coins": 0,
            "used_items": []
        },
        "hack_reason": 0,
        "sit_on_throne": false,
        "wta_curr_type": 0,
        "warm_game": {
            "type": 0,
            "level": 0
        },
        "role": 0,
        "championship_type": 1,
        "linkage_info": {
            "type": 0,
            "pirate_map_token_id": 0
        },
        "revenge_success_times": 0
    },
    "income": {
        "exp": 0,
        "coins": 0,
        "rank_points": 0,
        "kill_points": 0,
        "damage_points": 0,
        "level_before": 0,
        "level_after": 0,
        "exp_before": 0,
        "exp_after": 0,
        "coins_before": 0,
        "coins_after": 0,
        "coins_gained_today": 0,
        "coins_gain_limit": 0,
        "mmr_delta": 0,
        "ranking_points_delta": 0,
        "ranking_points_before": 0,
        "ranking_points_after": 0,
        "level_rewards": {
            "items": [],
            "coins": 0,
            "gems": 0,
            "exps": 0,
            "activeness": 0
        },
        "daily_reward_exp": 0,
        "daily_reward_coins": 0,
        "rank_before": 0,
        "rank_after": 0,
        "has_rank_upgrade_rewards": false,
        "is_rank": false,
        "is_logout_match": true,
        "honor_point_delta": 0,
        "game_drops": [],
        "is_loss_prevented": false,
        "coin_limit_event_bonus": 0,
        "debris_limit_event_bonus": 0,
        "ranking_points_detail": {
            "ranking_score": 0,
            "battle_score": 0,
            "newbie_score": 0,
            "victory_score": 0,
            "first_win_score": 0,
            "chicken_protect": false,
            "birth_island_quit_score": 0,
            "scale_ranking_score": 0,
            "scale_battle_score": 0
        },
        "race_point_delta": 0,
        "ranking_token_id": 0,
        "ranking_token_delta": 0,
        "ranking_token_num": 0,
        "coins_detail": {
            "coin_match": 0,
            "coin_clan_buff": 0,
            "coin_event_bonus": 0,
            "coin_card": 0,
            "coin_ranking": 0,
            "coin_championship": 0
        },
        "exp_detail": {
            "exp_match": 0,
            "exp_clan_buff": 0,
            "exp_event_bonus": 0,
            "exp_card": 0,
            "exp_ranking": 0,
            "exp_championship": 0
        },
        "pet_exp_detail": {
            "id": 0,
            "name": "",
            "level_before": 0,
            "level_after": 0,
            "exp_before": 0,
            "exp_after": 0,
            "skin_id": 0
        },
        "debris_detail": [],
        "ingame_items": [],
        "ranking_token_max": 0,
        "is_double_ranking_point_activity": false,
        "is_double_token_activity": false,
        "double_ranking_point_card_id": 0,
        "chip_num": 0,
        "no_deduct_card_id": 0,
        "is_championship": false,
        "pirate_map_award_id": 0,
        "mmr_after": 0
    }
}

Only match stats of the latest 14 days are available.

match_stats.match_mode:

match_stats.group_mode:

match_stats.game_mode:

Get Account Match Stats Summary

Request

{
    "account_id": "41000862",
    "start_time": 1573956600,
    "end_time": 1574064960,
    "match_mode": 1,
    "lock_region": "TW"
}

The search time range must not exceed 2 days (172800 sec).

match_mode:

Response

{
    "match_times": 3,
    "booyah_times": 2,
    "kills": 4
}

Get Account Basic Info

Request

?account_id=41000380

or

{"account_id": "41000380"}

Response

{
    "account_id": "41000380",
    "account_type": 1,
    "nickname": "apm1467",
    "create_time": 1562567180,
    "level": 1,
    "exp": 0,
    "region": "TW",
    "lock_region_time": 1562567180,
    "last_login_time": 1562822908,
    "role": 1
}

role:

Internally, roles are bitmasks. For example, for an account with both role 1 and 2, the role field will appear as 3.

Get Account Ranking Info

Request

?account_id=41000862&season_id=12

or

{
    "account_id": "41000862",
    "season_id": 12
}

Response

{
    "account_id": "41000862",
    "season_id": 12,
    "rank": 1,
    "ranking_points": 1000
}