> ## Documentation Index > Fetch the complete documentation index at: https://formcarry.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Upload an image > Uploads a logo and returns a URL. The upload does not change the form. You must put the response `url` into the corresponding field with a PATCH. Send the request as `multipart/form-data` with two parts: `file`, the image, and `use`, where it will be shown. | `use` | Put the returned `url` in | |---|---| | `self_email_notification_logo` | `self_email_notification.logo_url` (the email you get on every submission) | | `auto_response_logo` | `auto_response.logo_url` (the reply the person who submitted receives) | | `after_submit_logo` | `after_submit.page.logo_url` (the thank you page) | | `after_submit_logo_dark` | `after_submit.page.logo_dark_url` (the thank you page in its dark look) | Uploads need a paid plan. Images may be up to 5 MB. `self_email_notification_logo` and `auto_response_logo` only accept PNG, JPEG or GIF because email clients do not display WebP or SVG. The thank you page placements take all five. ## OpenAPI ````yaml https://api.formcarry.com/docs-json post /v1/forms/{form_id}/images openapi: 3.0.0 info: title: formcarry API description: >- Welcome to the formcarry API. Authenticate every request with an API key from your team's API page in the dashboard, sent as `Authorization: Bearer fc_live_...`. Requests and responses are JSON. Lists are paginated with a cursor: pass a response's `next_cursor` as `cursor` to get the next page, until `next_cursor` is null. Errors return a `code` you can act on and a `message` you can show. Every response includes an `X-Request-Id` header; quote it when you contact support. version: '1' contact: {} servers: - url: https://api.formcarry.com security: [] tags: - name: forms description: Your forms - name: submissions description: Submissions received by a form - name: me description: The key you are using - name: health description: Service status paths: /v1/forms/{form_id}/images: post: tags: - forms summary: Upload an image description: >- Uploads a logo and returns a URL. The upload does not change the form. You must put the response `url` into the corresponding field with a PATCH. Send the request as `multipart/form-data` with two parts: `file`, the image, and `use`, where it will be shown. | `use` | Put the returned `url` in | |---|---| | `self_email_notification_logo` | `self_email_notification.logo_url` (the email you get on every submission) | | `auto_response_logo` | `auto_response.logo_url` (the reply the person who submitted receives) | | `after_submit_logo` | `after_submit.page.logo_url` (the thank you page) | | `after_submit_logo_dark` | `after_submit.page.logo_dark_url` (the thank you page in its dark look) | Uploads need a paid plan. Images may be up to 5 MB. `self_email_notification_logo` and `auto_response_logo` only accept PNG, JPEG or GIF because email clients do not display WebP or SVG. The thank you page placements take all five. operationId: FormsController_uploadImage parameters: - name: form_id required: true in: path description: >- The form's id, as shown in the dashboard and in the form's endpoint URL example: AbC123xyz schema: type: string requestBody: required: true content: multipart/form-data: schema: type: object required: - file - use properties: file: type: string format: binary description: >- PNG, JPEG or GIF, up to 5 MB. The thank you page placements also take WebP and SVG; the email placements refuse them because email clients do not display those formats. use: type: string enum: - self_email_notification_logo - auto_response_logo - after_submit_logo - after_submit_logo_dark description: >- Where the image will be shown. One of `self_email_notification_logo` (the email you get on every submission), `auto_response_logo` (the reply the person who submitted receives), `after_submit_logo` (the thank you page) or `after_submit_logo_dark` (the thank you page in its dark look). name: type: string maxLength: 64 pattern: ^[A-Za-z0-9_-]+$ description: >- A name for the file. Letters, digits, dashes and underscores. responses: '201': description: '' content: application/json: schema: $ref: '#/components/schemas/UploadedImage' '400': description: >- The image part is missing, not an image, of a format the placement does not take, or `use` is unknown. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: invalid_parameter: summary: invalid_parameter value: error: type: invalid_request_error code: invalid_parameter message: >- Email clients do not display WebP or SVG images. Use a PNG, JPEG or GIF for email logos. param: file request_id: 2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a '401': description: The request carried no usable key or token. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: missing_bearer: summary: missing_bearer value: error: type: authentication_error code: missing_bearer message: >- Send your key as "Authorization: Bearer fc_live_..." on every request. request_id: 2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a invalid_key: summary: invalid_key value: error: type: authentication_error code: invalid_key message: >- This API key or access token is unknown, revoked or expired. request_id: 2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a wrong_audience: summary: wrong_audience value: error: type: authentication_error code: wrong_audience message: >- This access token was issued for a different resource. Authorize again for this server. request_id: 2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a '403': description: The key is valid but may not upload here. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: insufficient_scope: summary: insufficient_scope value: error: type: permission_error code: insufficient_scope message: This key is missing the forms:write scope. required: - forms:write request_id: 2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a plan_restricted: summary: plan_restricted value: error: type: permission_error code: plan_restricted message: >- You need to upgrade your plan to upload your logo & files request_id: 2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a team_inactive: summary: team_inactive value: error: type: permission_error code: team_inactive message: The team that owns this key is not active. request_id: 2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a '404': description: No such form for this key. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: form_not_found: summary: form_not_found value: error: type: invalid_request_error code: form_not_found message: No form with that id is accessible with this key. request_id: 2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a '413': description: The image is larger than 5 MB. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: payload_too_large: summary: payload_too_large value: error: type: invalid_request_error code: payload_too_large message: >- The request body is too large. JSON bodies may be up to 1 MB, image uploads up to 5 MB. request_id: 2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a '429': description: Slow down and retry after the Retry-After header. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests. request_id: 2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a scan_concurrency: summary: scan_concurrency value: error: type: rate_limit_error code: scan_concurrency message: >- At most 2 filtered submission requests may run at once per key. Wait for the running ones to finish. request_id: 2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a security: - api_key: [] components: schemas: UploadedImage: type: object properties: url: type: string example: https://cdn.formcarry.com/.../logo.png required: - url ErrorEnvelope: type: object properties: error: $ref: '#/components/schemas/ErrorBody' required: - error ErrorBody: type: object properties: type: type: string enum: - authentication_error - permission_error - invalid_request_error - rate_limit_error - api_error example: invalid_request_error code: type: string example: invalid_parameter message: type: string example: limit must not be greater than 100 param: type: string description: The offending parameter, when there is one example: limit required: description: >- On insufficient_scope: the scopes the request needs. Reissue the key with them. example: - submissions:write type: array items: type: string retry_after: type: number description: 'On scan_concurrency: seconds to wait before trying again.' example: 2 request_id: type: string description: Echoes X-Request-Id. Quote it when contacting support. example: 2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a required: - type - code - message - request_id securitySchemes: api_key: scheme: bearer bearerFormat: fc_live_... type: http ```` ## Related topics - [Formcarry API Overview](/docs/api/overview.md) - [Accept and Manage File Uploads](/docs/features/file-uploads.md) - [What every form needs](/docs/what-every-form-needs.md) - [API Authentication with Bearer Tokens](/docs/api/authentication.md) - [jQuery](/docs/frameworks/jquery.md)