Initiate File Uploads

Initiates file uploads to an entity’s profile.

Error codes

This operation may return the following PlayFab errors:

Error	Code
EntityFileOperationPending	1350

POST

File

InitiateFileUploads

Initiate File Uploads

curl --request POST \
  --url https://{titleId}.playfabapi.com/File/InitiateFileUploads \
  --header 'Content-Type: application/json' \
  --header 'X-EntityToken: <api-key>' \
  --data '
{
  "FileNames": [
    "avatar",
    "game_state"
  ],
  "Entity": {
    "Id": "ID",
    "Type": "title_player_account",
    "TypeString": "title_player_account"
  }
}
'

import requests

url = "https://{titleId}.playfabapi.com/File/InitiateFileUploads"

payload = {
    "FileNames": ["avatar", "game_state"],
    "Entity": {
        "Id": "ID",
        "Type": "title_player_account",
        "TypeString": "title_player_account"
    }
}
headers = {
    "X-EntityToken": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-EntityToken': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    FileNames: ['avatar', 'game_state'],
    Entity: {Id: 'ID', Type: 'title_player_account', TypeString: 'title_player_account'}
  })
};

fetch('https://{titleId}.playfabapi.com/File/InitiateFileUploads', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{titleId}.playfabapi.com/File/InitiateFileUploads",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'FileNames' => [
        'avatar',
        'game_state'
    ],
    'Entity' => [
        'Id' => 'ID',
        'Type' => 'title_player_account',
        'TypeString' => 'title_player_account'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-EntityToken: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{titleId}.playfabapi.com/File/InitiateFileUploads"

	payload := strings.NewReader("{\n  \"FileNames\": [\n    \"avatar\",\n    \"game_state\"\n  ],\n  \"Entity\": {\n    \"Id\": \"ID\",\n    \"Type\": \"title_player_account\",\n    \"TypeString\": \"title_player_account\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-EntityToken", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{titleId}.playfabapi.com/File/InitiateFileUploads")
  .header("X-EntityToken", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"FileNames\": [\n    \"avatar\",\n    \"game_state\"\n  ],\n  \"Entity\": {\n    \"Id\": \"ID\",\n    \"Type\": \"title_player_account\",\n    \"TypeString\": \"title_player_account\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{titleId}.playfabapi.com/File/InitiateFileUploads")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-EntityToken"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"FileNames\": [\n    \"avatar\",\n    \"game_state\"\n  ],\n  \"Entity\": {\n    \"Id\": \"ID\",\n    \"Type\": \"title_player_account\",\n    \"TypeString\": \"title_player_account\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "code": 200,
  "status": "OK",
  "data": {
    "ProfileVersion": 5,
    "UploadDetails": [
      {
        "FileName": "game_state",
        "UploadUrl": "https://..."
      },
      {
        "FileName": "avatar",
        "UploadUrl": "https://..."
      }
    ],
    "Entity": {
      "Id": "ID",
      "Type": "title_player_account",
      "TypeString": "title_player_account"
    }
  }
}

{
  "code": 123,
  "errorCode": 123,
  "status": "<string>",
  "error": "<string>",
  "errorMessage": "<string>",
  "errorDetails": {}
}

Authorizations

X-EntityToken

string

header

required

This API requires an Entity Session Token, available from the Entity GetEntityToken method.

Body

application/json

Returns URLs that may be used to upload the files for a profile 5 minutes. After using the upload calls FinalizeFileUploads must be called to move the file status from pending to live.

Entity

object

required

The entity to perform this action on.

Show child attributes

FileNames

string[]

required

Names of the files to be set. Restricted to a-Z, 0-9, '(', ')', '_', '-' and '.'

CustomTags

object

The optional custom tags associated with the request (e.g. build number, external trace identifiers, etc.).

ProfileVersion

number

Optional field used for concurrency control. By specifying the previously returned ProfileVersion value from the GetFiles API or other APIs, you can ensure that the file upload initiation is performed only if the profile has not been updated since you last loaded that version. If the profile for the same entity has been updated, the operation will fail with an EntityProfileVersionMismatch error. The conflicting update can be caused by any operation that modifies the entity profile, including SetObjects, FinalizeFileUploads, and UpdateStatistics.

Response

code

integer

The Http status code. If X-ReportErrorAsSuccess header is set to true, this will report the actual http error code.

status

string

The Http status code as a string.

data

object

Show child attributes

Example:

{
  "ProfileVersion": 5,
  "UploadDetails": [
    {
      "FileName": "game_state",
      "UploadUrl": "https://..."
    },
    {
      "FileName": "avatar",
      "UploadUrl": "https://..."
    }
  ],
  "Entity": {
    "Id": "ID",
    "Type": "title_player_account",
    "TypeString": "title_player_account"
  }
}

Last modified on October 1, 2026

⌘I

Initiate File Uploads

curl --request POST \
  --url https://{titleId}.playfabapi.com/File/InitiateFileUploads \
  --header 'Content-Type: application/json' \
  --header 'X-EntityToken: <api-key>' \
  --data '
{
  "FileNames": [
    "avatar",
    "game_state"
  ],
  "Entity": {
    "Id": "ID",
    "Type": "title_player_account",
    "TypeString": "title_player_account"
  }
}
'

import requests

url = "https://{titleId}.playfabapi.com/File/InitiateFileUploads"

payload = {
    "FileNames": ["avatar", "game_state"],
    "Entity": {
        "Id": "ID",
        "Type": "title_player_account",
        "TypeString": "title_player_account"
    }
}
headers = {
    "X-EntityToken": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-EntityToken': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    FileNames: ['avatar', 'game_state'],
    Entity: {Id: 'ID', Type: 'title_player_account', TypeString: 'title_player_account'}
  })
};

fetch('https://{titleId}.playfabapi.com/File/InitiateFileUploads', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{titleId}.playfabapi.com/File/InitiateFileUploads",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'FileNames' => [
        'avatar',
        'game_state'
    ],
    'Entity' => [
        'Id' => 'ID',
        'Type' => 'title_player_account',
        'TypeString' => 'title_player_account'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-EntityToken: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{titleId}.playfabapi.com/File/InitiateFileUploads"

	payload := strings.NewReader("{\n  \"FileNames\": [\n    \"avatar\",\n    \"game_state\"\n  ],\n  \"Entity\": {\n    \"Id\": \"ID\",\n    \"Type\": \"title_player_account\",\n    \"TypeString\": \"title_player_account\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-EntityToken", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{titleId}.playfabapi.com/File/InitiateFileUploads")
  .header("X-EntityToken", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"FileNames\": [\n    \"avatar\",\n    \"game_state\"\n  ],\n  \"Entity\": {\n    \"Id\": \"ID\",\n    \"Type\": \"title_player_account\",\n    \"TypeString\": \"title_player_account\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{titleId}.playfabapi.com/File/InitiateFileUploads")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-EntityToken"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"FileNames\": [\n    \"avatar\",\n    \"game_state\"\n  ],\n  \"Entity\": {\n    \"Id\": \"ID\",\n    \"Type\": \"title_player_account\",\n    \"TypeString\": \"title_player_account\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "code": 200,
  "status": "OK",
  "data": {
    "ProfileVersion": 5,
    "UploadDetails": [
      {
        "FileName": "game_state",
        "UploadUrl": "https://..."
      },
      {
        "FileName": "avatar",
        "UploadUrl": "https://..."
      }
    ],
    "Entity": {
      "Id": "ID",
      "Type": "title_player_account",
      "TypeString": "title_player_account"
    }
  }
}

{
  "code": 123,
  "errorCode": 123,
  "status": "<string>",
  "error": "<string>",
  "errorMessage": "<string>",
  "errorDetails": {}
}

PlayFab API

PlayFab REST API References

Initiate File Uploads

Error codes

Authorizations

Body

Response