About the Attachments API

The Attachments API allows you to create and manage a contact's file attachments in a site, making it easier to organize, access, and maintain important attachments directly linked to a contact.

With the Attachments API, you can:

  • Generate secure upload URLs for attaching files to contacts.
  • Retrieve and list all attachments associated with a specific contact.
  • Delete attachments that are no longer needed.

Before you begin

Before you start to code, it's important to note that this API should be used in conjunction with the Contacts API as every attachment is associated with a contact ID.

Terminology

  • Attachment: A file attached to a contact, which can be an image or document.
  • MimeType: A media type that indicates the format of a file. See the list of supported mime types.
Did this help?

Supported Mime Types

The table below provides a list of all supported mime types, which can be used in the mimType field of the attachments object.

Mime TypeExtension
text/csv.csv
application/msword.doc
application/vnd.openxmlformats-officedocument.wordprocessingml.document.docx
application/vnd.openxmlformats-officedocument.wordprocessingml.template.dotx
application/vnd.ms-excel/.xls
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.xlsx
application/vnd.openxmlformats-officedocument.spreadsheetml.template.xltx
application/vnd.ms-powerpoint.ppt
application/vnd.openxmlformats-officedocument.presentationml.presentation.pptx
application/vnd.openxmlformats-officedocument.presentationml.template.potx
application/vnd.openxmlformats-officedocument.presentationml.slideshow.ppsx
application/pdf.pdf

In addition, all images mime types that starts with image/ are valid except:

Unsupported Image Mime Types
image/tiff
image/svg+xml
image/bmp
image/x-bmp
image/bmp
image/vnd.zbrush.pcx"
image/x-pcx
image/x-xcf
image/x-icon
image/ico
image/icon
image/vnd.microsoft.icon
image/x-pict
image/x‑portable‑bitmap
image/x‑portable‑graymap
image/x‑portable‑pixmap
image/x‑portable‑anymap
image/sgi
image/webp
Did this help?

Attachments: Sample Flow

This article presents a possible use case and corresponding sample flow that you can support. This can be a helpful jumping-off point as you plan your implementation.

Manage documents for real estate properties

In this scenario, you create an app that allows real estate agents to securely upload, manage, and access property-related documents such as contracts, deeds, and inspection reports by attaching them to the relevant client profile on the agent's site.

Flow

To create an app for real estate agents to manage and access property document attachments through their site, follow this basic flow:

  1. Prompt the real estate agent to select a file to upload upon clicking a button.
  2. Call the Generate Attachment Upload Url method to obtain the URL for upload.
  3. Use the generated URL to upload the document as an attachment to the relevant contact profile. Refer to the Upload API for details on how to use the upload URL.
  4. Call the List Attachments method to display a list of all the contact's documents.
  5. When an agent needs to view a specific document, allow them to select it from the list and then call the Get Attachment method to retrieve and display the file.
  6. If the agent needs to delete a file, allow them to select it and then call the Delete Attachment method.
Did this help?

Attachment Object


Manage Contact Attachments

Properties
idstringRead-onlyformat GUID

Attachment ID.


previewImagePreviewImageRead-only

Details of the preview image reduced size when the attachment is of type IMAGE.


fileNamestringRead-only

Name of the attachment file.


mimeTypestringRead-only

Mime type of the attachment. See supported mime types (REST|SDK).


attachmentTypestringRead-only

Type of the attachment.


ONE OF:

imageImage

Image details when the attachment type is IMAGE.


documentDocument

Document details when the attachment type is OTHER.

ContactAttachment
JSON
{ "id": "ed707c00-27e8-11eb-ae1e-6dc6f7cc14d1", "mediaItem": { "document": { "id": "361c0d38e97a4d9691d7a3b6dfbde96b", "url": "https://www.wix.com/contacts-server/api/v1/metasite/fa9e5039-9ebb-4045-9724-706afa049542/513c1b1c-61b6-427d-a7f8-ceeedb1eb763/media/download/361c0d38e97a4d9691d7a3b6dfbde96b" } }, "fileName": "data.csv", "mimeType": "text/csv", "attachmentType": "OTHER" }
Did this help?

POST

Generate Attachment Upload Url


Generates an upload URL for uploading a file as an attachment to a specified contact.

To learn how to use the generated upload URL in the response to upload an attachment file, see the Upload API (SDK | REST).

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Contact Attachments
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/contacts/v4/attachments/{contactId}/upload-url

Path Params
contactIdstringRequired

ID of the contact for whom the attachment is being uploaded.

Body Params
fileNamestringRequiredminLength 1maxLength 260

File name of the attachment including the extension, for example, contact-cv.pdf.


mimeTypestringRequiredminLength 1maxLength 255

Mime type of the attachment file, for example, application/pdf. See supported mime types (REST| SDK).

Response Object
uploadUrlstringformat WEB_URL

The URL for uploading a file as an attachment to the contact.

Generate Attachment Upload Url Example 1
Request
cURL
curl -X POST \ 'https://www.wixapis.com/contacts/v4/attachments/513c1bfc-61b6-427d-a7f8-ceeedb1eb763/upload-url' \ -H 'Authorization: <AUTH>' \ --data-binary '{ "contactId": "513c1bfc-61b6-427d-a7f8-ceeedb1eb763", "fileName": "my-data.csv", "mimeType": "text/csv" }'
Response
JSON
{ "uploadUrl": "https://wixmp-8be454c954980f083caba37c.appspot.com/_ah/upload/AMmfu6Z00Ya5E7SPa7dsD0-iPgB_7_mbS5-I2wxanQjYsM6N99Yd6Tb9ty86XlpULTnXVoYj_ryWmrC4NA3YBrA6W7Ln_86kPeDvoYRXLJ5geqsnTlbTdezpsO1NMvm4rm2B4nrMeunH2vgmBiiqyxk5g1fxJuuH6Tzpx0eq-tDRkeV2tLXwffLDdo-gON4eHrYjSOq7ql9XCX1-Ml88mQFUg4h_jw-qaBpVbsGLrjHbeaijM38VtiqvExHUSjVkuPc4GrlnB35nFHwlCx_8hn2qnXQTHcdZlOpRASbL4Dt4KmaVDx0d0bg/ALBNUaYAAAAAX8jL_p1GRljz1mIXmSwnVPse-iWgiw7u/" }
Event TriggersThis method triggers the following events:
Did this help?

GET

List Attachments


Retrieves a list of attachments associated with a specified contact.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Contact Attachments
Learn more about app permissions.
Endpoint
GET
https://www.wixapis.com/contacts/v4/attachments/{contactId}

Path Params
contactIdstringRequired

Contact ID for the attachments to be listed.

Query Params
paging.limitintegerminimum 0maximum 100format int32

Number of items to return.

Default: 100 Max: 100


paging.offsetintegerminimum 0format int32

Number of items to skip in the current sort order.

Response Object
attachmentsArray <ContactAttachment>

List of attachments for the specified contact.


metadataMetadata

Metadata for the paginated results.

List Attachments Example 1
Request
cURL
curl -X GET \ 'https://www.wixapis.com/contacts/v4/attachments' --data-binary '{ "contactId": "513c1bfc-61b6-427d-a7f8-ceeedb1eb763" }' -H 'Content-Type: application/json' -H 'Authorization: <AUTH>'
Response
JSON
{ "attachments": [ { "id": "1e7efe60-355a-11eb-b032-19d0ca8630af", "mediaItem": { "document": { "id": "2360f96cdd184dbb122e78291ec86748", "url": "https://www.wix.com/contacts-server/api/v1/metasite/f69e5039-9ebb-4045-9724-706afa049542/513c1bfc-61b6-427d-a7f8-ceeedb1eb763/media/download/2360f96cdd184dbb122e78291ec86748" } }, "fileName": "my-csv.csv", "mimeType": "text/csv", "attachmentType": "OTHER" }, { "id": "23e76c70-35aa-11eb-b032-19d0ca86301f", "mediaItem": { "image": { "id": "7afda7abbf0c4981b752650133683d3f", "url": "https://www.wix.com/contacts-server/api/v1/metasite/f69e5039-9ebb-4045-9724-706afa049542/513c1bfc-61b6-427d-a7f8-ceeedb1eb763/media/download/7afda7abbf0c4981b752650133683d3f", "height": 0, "width": 0 } }, "previewImage": { "id": "7afda7abbf0c4981b752650133683d3f", "url": "https://www.wix.com/contacts-server/api/v1/metasite/f69e5039-9ebb-4045-9724-706afa049542/513c1bfc-61b6-427d-a7f8-ceeedb1eb763/media/download/7afda7abbf0c4981b752650133683d3f?preview=true", "height": 0, "width": 0 }, "fileName": "my-image.jpg", "mimeType": "image/jpeg", "attachmentType": "IMAGE" }, { "id": "295do0f0-355h-11eb-b032-19d0ca86307f", "mediaItem": { "document": { "id": "c97c337683494b74b165f9ee36ac2052", "url": "https://www.wix.com/contacts-server/api/v1/metasite/f69e5039-9ebb-4045-9724-706afa049542/513c1bfc-61b6-427d-a7f8-ceeedb1eb763/media/download/c97c337683494b74b165f9ee36ac2052" } }, "fileName": "my-pdf.pdf", "mimeType": "application/pdf", "attachmentType": "OTHER" } ], "metadata": { "count": 3, "offset": 0, "total": 3 } }
Did this help?

GET

Get Attachment


Retrieves the specified attachment for the specified contact.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Contact Attachments
Learn more about app permissions.
Endpoint
GET
https://www.wixapis.com/contacts/v4/attachments/{contactId}/{attachmentId}

Path Params
contactIdstringRequired

Contact ID for the attachment to retrieve.


attachmentIdstringRequired

Attachment ID to retrieve.

Response Object
attachmentAttachment

The requested attachment.

Get Attachment Example 1
Request
cURL
curl -X GET \ 'https://www.wixapis.com/contacts/v4/attachments/513c1bfc-61b6-427d-a7f8-ceeedb1eb763/1e7efe60-355a-11eb-b032-19d0ca8630af' \ -H 'Authorization: <AUTH>'
Response
JSON
{ "attachment": { "id": "295do0f0-355h-11eb-b032-19d0ca86307f", "mediaItem": { "document": { "id": "c97c337683494b74b165f9ee36ac2052", "url": "https://www.wix.com/contacts-server/api/v1/metasite/f69e5039-9ebb-4045-9724-706afa049542/513c1bfc-61b6-427d-a7f8-ceeedb1eb763/media/download/c97c337683494b74b165f9ee36ac2052" } }, "fileName": "my-pdf.pdf", "mimeType": "application/pdf", "attachmentType": "OTHER" } }
Did this help?

DELETE

Delete Attachment


Deletes the specified attachment from the specified contact.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Contact Attachments
Learn more about app permissions.
Endpoint
DELETE
https://www.wixapis.com/contacts/v4/attachments/{contactId}/{attachmentId}

Path Params
contactIdstringRequired

Contact ID for the attachment to delete.


attachmentIdstringRequired

Attachment ID to delete.

Response Object
Returns an empty object.
Delete Attachment Example 1
Request
cURL
curl -X DELETE \ 'https://www.wixapis.com/contacts/v4/attachments/513c1bfc-61b6-427d-a7f8-ceeedb1eb763/1e7efe60-355a-11eb-b032-19d0ca8630af' \ -H 'Authorization: <AUTH>'
Response
JSON
{}
Event TriggersThis method triggers the following events:
Did this help?

Attachment Created


Permissions
Manage Contact Attachments
Learn more about app permissions.
Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring

Unique event ID. Allows clients to ignore duplicate webhooks.


entityFqdnstring

Fully qualified domain name of the entity associated with the event. Expected wix.contacts.v4.attachment.


slugstring

Event name. Expected created.


entityIdstring

ID of the entity associated with the event.


eventTimestringformat date-time

Event timestamp.


triggeredByAnonymizeRequestboolean

Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).


originatedFromstring

If present, indicates the action that triggered the event.


createdEventCreatedEvent

Event information.

Event Body

The data payload will include the following as an encoded JWT:

JSON
{ "data": { "eventType": "wix.contacts.v4.attachment_created", "instanceId": "<app-instance-id>", "data": "<stringified-JSON>", // The identity field is sent as a stringified JSON "identity": { "identityType": "<identityType>", // ANONYMOUS_VISITOR, MEMBER, WIX_USER, APP "anonymousVisitorId": "<anonymousVisitorId>", // in case of ANONYMOUS_VISITOR "memberId": "<memberId>", // in case of MEMBER "wixUserId": "<wixUserId>", // in case of WIX_USER "appId": "<appId>" // in case of APP } } }

AttachmentCreated
JSON
{ "id": "efb2e820-0b15-4457-b038-a652a8ba041f", "entityFqdn": "wix.contacts.v4.attachment", "slug": "created", "entityId": "b783822b-3bf5-47a6-b0d9-3c73efdade84", "createdEvent": { "entityAsJson": { "id": "b783822b-3bf5-47a6-b0d9-3c73efdade84", "image": { "id": "e6711764cfb4439abbf11f01c161e34f", "url": "https://wixmp-8be454c954980f083caba37c.wixmp.com/sites/2ca83e30-1dd3-414e-a4ac-166f2dcf97b8/contact/fa15331a-8990-4fa4-ad7d-3c3393a9a298/b783822b-3bf5-47a6-b0d9-3c73efdade84.jpeg?token=eyJhbGciOiJIUzI1NiJ9.eyJzdFiMDc3MISI6IjUzOTY2M6IldoYXRzQXBwIElt&filename=picture.jpeg", "height": 0, "width": 0, "urlExpirationDate": "2024-12-29T21:23:04.842113760Z" }, "previewImage": { "id": "524b2ed50f474da3ab017856b016d536", "url": "https://wixmp-8be454c954980f083caba37c.wixmp.com/sites/2ca83e30-1dd3-414e-a4ac-166f2dcf97b8/contact/fa15331a-8990-4fa4-ad7d-3c3393a9a298/b783822b-3bf5-47a6-b0d9-3c73efdade84.preview.jpeg?token=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1cm46YXBwOmY1ODg2NzI1MzJ&filename=picture.jpeg", "height": 768, "width": 1024, "urlExpirationDate": "2024-12-29T21:23:04.843469862Z" }, "fileName": "picture.jpeg", "mimeType": "image/jpeg", "attachmentType": "IMAGE" } }, "eventTime": "2024-12-15T21:23:05.845283290Z", "triggeredByAnonymizeRequest": false }
Did this help?

Attachment Deleted


Permissions
Manage Contact Attachments
Learn more about app permissions.
Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring

Unique event ID. Allows clients to ignore duplicate webhooks.


entityFqdnstring

Fully qualified domain name of the entity associated with the event. Expected wix.contacts.v4.attachment.


slugstring

Event name. Expected deleted.


entityIdstring

ID of the entity associated with the event.


eventTimestringformat date-time

Event timestamp.


triggeredByAnonymizeRequestboolean

Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).


originatedFromstring

If present, indicates the action that triggered the event.


deletedEventstruct

Event information.

Event Body

The data payload will include the following as an encoded JWT:

JSON
{ "data": { "eventType": "wix.contacts.v4.attachment_deleted", "instanceId": "<app-instance-id>", "data": "<stringified-JSON>", // The identity field is sent as a stringified JSON "identity": { "identityType": "<identityType>", // ANONYMOUS_VISITOR, MEMBER, WIX_USER, APP "anonymousVisitorId": "<anonymousVisitorId>", // in case of ANONYMOUS_VISITOR "memberId": "<memberId>", // in case of MEMBER "wixUserId": "<wixUserId>", // in case of WIX_USER "appId": "<appId>" // in case of APP } } }

AttachmentDeleted
JSON
{ "id": "191257e6-3a2b-40bb-bd1a-d2b0207ee01d", "entityFqdn": "wix.contacts.v4.attachment", "slug": "deleted", "entityId": "68150352-7401-4b22-a2e8-fd2fd8a213fa", "deletedEvent": {}, "eventTime": "2024-12-15T21:09:25.316232816Z", "triggeredByAnonymizeRequest": false }
Did this help?