Requests

Perform GET, POST, PUT, and DELETE operations on API objects

Below are the HTTP methods for performing requests on the API objects. Requests can be executed on a single or list of known objects by their object id, or a group of objects based on query parameters by using Conditional Queries.

Method	Description	Example
`GET`	Select one or many objects	`GET /transactions`
`POST`	Create one or many objects	`POST /transactions`
`PUT`	Update one or many objects	`PUT /transactions`
`DELETE`	Delete one or many objects	`DELETE /transactions`

Selecting Objects

Select individual or multiple objects using the HTTP method GET.

get.py

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
transaction = pl.Transaction.get('txn_3bW9JN4CCJFkc9ukQ0umW')

Request: GET https://api.payload.com/transactions/{id}

get.py

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
payments = pl.Transaction.filter_by( status='processed' ).all()

Request Multiple Objects: GET https://api.payload.com/transactions/?attr=value

Filter results using conditional queries.

Creating Objects

Create individual or multiple objects using the HTTP method POST.

create.py

import payload
 
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
account = pl.Account.create(
    type="customer",
    name='Matt Perez',
    contact_details={'email': '[email protected]'},
)

Create Request: POST https://api.payload.com/customers

Request Body:

{
  "email": "[email protected]",
  "name": "Matt Perez"
}

create.py

import payload
 
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
accounts = pl.create(
    [
        pl.Account(
            type='customer',
            name='Matt Perez',
            contact_details={'email': '[email protected]'},
        ),
        pl.Account(
            type='customer',
            name='Andrea Kearney',
            contact_details={'email': '[email protected]'},
        ),
    ]
)

Create Multiple Objects: POST https://api.payload.com/customers

Request Body:

{
  "object": "list",
  "values": [
    {
      "email": "[email protected]",
      "name": "Matt Perez"
    },
    {
      "email": "[email protected]",
      "name": "Matt Perez"
    }
  ]
}

Updating Objects

Update individual or multiple objects using the HTTP method PUT.

update.py

import payload
 
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Example object instances
account = pl.Account.get('acct_example123')
 
account.update(contact_details={'email': "[email protected]"})

Update Request: PUT https://api.payload.com/customers/{id}

Request Body:

{
  "email": "[email protected]"
}

update.py

import payload
 
pl = payload.Session("secret_key_3bW9...", api_version="v2")
 
accounts = pl.Account.filter_by(
    contact_details={"email": "[email protected]"}
).update(contact_details={"email": "[email protected]"})

Update Query: PUT https://api.payload.com/customers/[email protected]&mode=query

Request Body:

{
  "email": "[email protected]"
}

When performing updates by query, it is required to include the mode=query flag. This flag is a safety feature implemented to prevent accidental bulk updates when a select operation was intended instead.

update.py

import payload
 
pl = payload.Session("secret_key_3bW9...", api_version="v2")
# Example object instances
account1 = pl.Account.get("acct_example1")
account2 = pl.Account.get("acct_example2")
 
accounts = pl.update(
    [
        [account1, {"contact_details": {"email": "[email protected]"}}],
        [account2, {"contact_details": {"email": "[email protected]"}}],
    ]
)

Update Multiple Objects: PUT https://api.payload.com/customers

Request Body:

{
  "object": "list",
  "values": [
    {
      "id": "acct_3bW9JN4OEmUpEezSq6TJY",
      "email": "[email protected]"
    },
    {
      "id": "acct_3bW9JN4OmbDd2Kg8bdK4W",
      "email": "[email protected]"
    }
  ]
}

Deleting Objects

Delete individual or multiple objects using the HTTP method DELETE.

delete.py

import payload
 
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Example object instances
account = pl.Account.get('acct_example123')
 
account.delete()

Delete Request: DELETE https://api.payload.com/customers/{id}

delete.py

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
deleted_accnts = pl.Account\
	.filter_by(email='[email protected]')\
	.delete()

Delete Query: DELETE https://api.payload.com/customers/[email protected]&mode=query

When performing deletes by query, it is required to include the mode=query flag. This flag is a safety feature implemented to prevent accidental bulk deletes when a select operation was intended instead.

delete.py

import payload
 
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Example object instances
account1 = pl.Account.get('acct_example1')
account2 = pl.Account.get('acct_example2')
 
deleted_accnts = pl.delete([account1, account2])

Delete Multiple Objects: DELETE https://api.payload.com/customers

Request Body:

{
  "object": "list",
  "values": [
    {
      "id": "acct_3bW9JN4OEmUpEezSq6TJY"
    },
    {
      "id": "acct_3bW9JN4OmbDd2Kg8bdK4W"
    }
  ]
}

Authentication Errors