Attach a File to a Record

When you need to attach a file to a record by using the contract-based REST API, you access the needed URL with the PUT HTTP method and pass the file in the request body. See the following sections for details on the request and the response.

HTTP Method and URL

If you need to attach a file to a top-level or detail record of any nesting level in MYOB Acumatica, you use the PUT HTTP method.

To get the URL for attaching a file to a particular record, you should obtain the record from MYOB Acumatica; in the returned JSON representation of the record, you find the value of the _links/files:put field. For information on how to retrieve a record from MYOB Acumatica, see Retrieve a Record by Key Fields and Retrieve a Record by ID. The value of the _links/files:put field for the desired record is part of the URL template that must be used in a request for attaching a file.

For example, suppose that you have retrieved the stock item record from a local MYOB Acumatica instance with the name AcumaticaDB. This record contains the following _links/files:put field value: /AcumaticaDB/entity/Default/23.200.001/files/PX.Objects.IN.InventoryItemMaint/Item/cae53ce0-1614-e511-9b82-c86000dddf0b/{filename}. If you want to attach the file.dat file to this record, you use the following HTTP method and URL.

PUT http://AcumaticaDB/entity/Default/23.200.001/files/PX.Objects.IN.InventoryItemMaint/Item/cae53ce0-1614-e511-9b82-c86000dddf0b/file.dat

Note: There is also an old way to attach a file to a top-level record in MYOB Acumatica that is kept for backward compatibility. Following it, you use the PUT HTTP method and the following URL:

http://<Base
                    endpoint URL>/<Top-level entity>/<Key value 1>/<Key value
                    2>/files/<File name>

. You address a record to which you are going to attach the file <File name> by the values <Key value 1> and <Key value 2> of its key fields.

Request Headers

You can specify the following headers in the request.


Header	Description
Accept	Specifies the format of the response body, which should be application/json.
Content-Type	Specifies the format of the request body, which should be application/octet-stream.

Request Body

You pass the file to be attached in the request body.

Response Status Codes

The following table lists the HTTP status codes that the system returns for a request that attaches a file to a record.


Code	Description
204	The request has been completed successfully. The file is attached. The `Location` header of the response contains the URL that you can use to retrieve the file from the system.
401	The user is not signed in to the system.
403	The user has insufficient rights to access the MYOB Acumatica form that corresponds to the entity.
429	The number of requests has exceeded the limit imposed by the license (see License Restrictions for API Users).
500	An internal server error has occurred.

Example

Tip: In the request examples below, <MYOB Acumatica instance URL> is the URL of the MYOB Acumatica instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

The following request shows an example of the retrieval of the EJECTOR03 stock item.

GET /EJECTOR03?$select=InventoryID HTTP/1.1
Host: [<MYOB Acumatica instance URL>]/entity/Default/23.200.001/StockItem
Accept: application/json
Content-Type: application/json

Suppose that the request above returns the following response body.

{
    "id": "a0f8594a-7de2-e811-b816-00155d408001",
    "rowNumber": 1,
    "note": {
        "value": ""
    },
    "InventoryID": {
        "value": "EJECTOR03"
    },
    "custom": {},
    "_links": {
        "self": "/<MYOB Acumatica instance name>/entity/Default/23.200.001/
StockItem/a0f8594a-7de2-e811-b816-00155d408001",
        "files:put": "/<MYOB Acumatica instance name>/entity/Default/23.200.001/
files/PX.Objects.IN.InventoryItemMaint/Item/a0f8594a-7de2-e811-b816-00155d408001/{filename}"
    }
}

The following request attaches the T2MCRO.jpg file to the EJECTOR03 stock item.

PUT /a0f8594a-7de2-e811-b816-00155d408001/T2MCRO.jpg HTTP/1.1
Host: [<MYOB Acumatica instance URL>]/entity/Default/23.200.001/files/
    PX.Objects.IN.InventoryItemMaint/Item
Accept: application/json
Content-Type: application/octet-stream

"<file contents here>"