> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.withpersona.com/2025-10-27/api-reference/importers/import-face-lists/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.withpersona.com/_mcp/server. # Import Face Lists POST https://api.withpersona.com/api/v1/importer/list-item/faces Content-Type: multipart/form-data Bulk import face List Items by uploading image files. Each file being a new List Item. We recommend uploading max 50 images (with average image size of 500KB) at a time. IMPORTANT: You must ensure proper consent for processing of biometrics is in place prior to using face Lists. Reference: https://docs.withpersona.com/api-reference/importers/import-face-lists ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Query parameters - `include` (string, optional) — A comma-separated list of relationship paths. This can be used to customize which related resources will be fully serialized in the `included` key in the response. See [Serialization](https://docs.withpersona.com/serialization#inclusion-of-related-resources) for more details. - `fields` (map from string to string, optional) — Comma-separated list(s) of attributes to include in the response. This can be used to customize which attributes will be serialized in the response. See [Serialization](https://docs.withpersona.com/serialization#sparse-fieldsets) for more details. ### Headers - `Key-Inflection` (enum, optional) — Determines casing for the API response. - Allowed values: `camel`, `kebab`, `snake` - `Idempotency-Key` (string, optional) — Ensures the request is idempotent. - `Persona-Version` (enum, optional) — Server API version. More info on versioning can be found [here](https://docs.withpersona.com/versioning). - Allowed values: `2025-12-08`, `2025-10-27`, `2023-01-05`, `2022-09-01`, `2021-08-18`, `2021-07-05`, `2021-02-21`, `2020-05-18` ### Body (multipart/form-data) This endpoint expects a multipart form. - `data` (ImporterListItemFacesPostRequestBodyContentMultipartFormDataSchemaData, required) ## Response ### 201 This endpoint returns an Importer object. - `data` (Face List Item Importer, required) — An Importer for face List Items IMPORTANT: You must ensure proper consent for processing of biometrics is in place prior to using face Lists. ## Errors ### 400 Bad Request Error The request was unacceptable, often due to invalid parameters. - `errors` (list of ImporterListItemFacesPostResponsesContentApplicationJsonSchemaErrorsItems, optional) ### 401 Unauthorized Error An invalid API key was provided. - `errors` (list of ImporterListItemFacesPostResponsesContentApplicationJsonSchemaErrorsItems, optional) ### 403 Forbidden Error The given API key doesn’t have permissions to perform the request or a quota has been exceeded. - `errors` (list of ImporterListItemFacesPostResponsesContentApplicationJsonSchemaErrorsItems, optional) ### 409 Conflict Error The request conflicts with another request, often due to attempting to create a duplicate resource. - `errors` (list of ImporterListItemFacesPostResponsesContentApplicationJsonSchemaErrorsItems, optional) ### 422 Unprocessable Entity Error The request modifies the resource in an unacceptable way, often due to an invalid action or parameter. - `errors` (list of ImporterListItemFacesPostResponsesContentApplicationJsonSchemaErrorsItems, optional) ### 429 Too Many Requests Error Your organization’s rate limit has been exceeded. We recommend an exponential backoff on requests. - `errors` (list of ImporterListItemFacesPostResponsesContentApplicationJsonSchemaErrorsItems, optional) ## Types ### Face List Item Importer An Importer for face List Items IMPORTANT: You must ensure proper consent for processing of biometrics is in place prior to using face Lists. - `id` (string, optional) — Unique identifier for this Importer. Starts with `mprt_`. - `attributes` (importer-shared-attributes, optional) ### ImporterListItemFacesPostResponsesContentApplicationJsonSchemaErrorsItems - `title` (string, optional) - `details` (string, optional) ### importer-shared-attributes - `completed-at` (datetime, optional, nullable) - `created-at` (string, optional) - `duplicate-count` (integer, optional, default: 0) - `error-count` (integer, optional, default: 0) - `status` (string, optional) — Possible values: - pending - ready - errored Do not assume this is a static enumeration; Persona may add new values in the future without a versioned update. - `successful-count` (integer, optional, default: 0) ## Examples **Request** ```json { "data": { "attributes": { "image-files": [ "string" ], "list-id": "string" } } } ``` **Response** ```json { "data": { "id": "mprt_TKqquVbHaSVYqgWhxNjuYDjQ", "attributes": { "completed-at": null, "created-at": "2020-07-12T17:16:54.656Z", "duplicate-count": 0, "error-count": 0, "status": "pending", "successful-count": 0 }, "type": "importer/list-item/face" } } ``` **SDK Code** ```python Created import requests url = "https://api.withpersona.com/api/v1/importer/list-item/faces" payload = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"data\"\r\n\r\n{\n \"attributes\": {\n \"image-files\": [\n \"string\"\n ],\n \"list-id\": \"string\"\n }\n}\r\n-----011000010111000001101001--\r\n" headers = { "Authorization": "Bearer ", "Content-Type": "multipart/form-data; boundary=---011000010111000001101001" } response = requests.post(url, data=payload, headers=headers) print(response.json()) ``` ```javascript Created const url = 'https://api.withpersona.com/api/v1/importer/list-item/faces'; const form = new FormData(); form.append('data', '{ "attributes": { "image-files": [ "string" ], "list-id": "string" } }'); const options = {method: 'POST', headers: {Authorization: 'Bearer '}}; options.body = form; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Created package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.withpersona.com/api/v1/importer/list-item/faces" payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"data\"\r\n\r\n{\n \"attributes\": {\n \"image-files\": [\n \"string\"\n ],\n \"list-id\": \"string\"\n }\n}\r\n-----011000010111000001101001--\r\n") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Created require 'uri' require 'net/http' url = URI("https://api.withpersona.com/api/v1/importer/list-item/faces") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"data\"\r\n\r\n{\n \"attributes\": {\n \"image-files\": [\n \"string\"\n ],\n \"list-id\": \"string\"\n }\n}\r\n-----011000010111000001101001--\r\n" response = http.request(request) puts response.read_body ``` ```java Created import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.withpersona.com/api/v1/importer/list-item/faces") .header("Authorization", "Bearer ") .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"data\"\r\n\r\n{\n \"attributes\": {\n \"image-files\": [\n \"string\"\n ],\n \"list-id\": \"string\"\n }\n}\r\n-----011000010111000001101001--\r\n") .asString(); ``` ```php Created request('POST', 'https://api.withpersona.com/api/v1/importer/list-item/faces', [ 'multipart' => [ [ 'name' => 'data', 'contents' => '{ "attributes": { "image-files": [ "string" ], "list-id": "string" } }' ] ] 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp Created using RestSharp; var client = new RestClient("https://api.withpersona.com/api/v1/importer/list-item/faces"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddParameter("undefined", "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"data\"\r\n\r\n{\n \"attributes\": {\n \"image-files\": [\n \"string\"\n ],\n \"list-id\": \"string\"\n }\n}\r\n-----011000010111000001101001--\r\n", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Created import Foundation let headers = ["Authorization": "Bearer "] let parameters = [ [ "name": "data", "value": "{ \"attributes\": { \"image-files\": [ \"string\" ], \"list-id\": \"string\" } }" ] ] let boundary = "---011000010111000001101001" var body = "" var error: NSError? = nil for param in parameters { let paramName = param["name"]! body += "--\(boundary)\r\n" body += "Content-Disposition:form-data; name=\"\(paramName)\"" if let filename = param["fileName"] { let contentType = param["content-type"]! let fileContent = String(contentsOfFile: filename, encoding: String.Encoding.utf8) if (error != nil) { print(error as Any) } body += "; filename=\"\(filename)\"\r\n" body += "Content-Type: \(contentType)\r\n\r\n" body += fileContent } else if let paramValue = param["value"] { body += "\r\n\r\n\(paramValue)" } } let request = NSMutableURLRequest(url: NSURL(string: "https://api.withpersona.com/api/v1/importer/list-item/faces")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```