Help Center

Catalogs

GET /catalogs/{catalog-id}

This method returns a catalog with its items. Without filters, it returns all available items. To get only the rows with specific column values, pass pairs of the column and value parameters. For several conditions, repeat both parameters for each of them — an item must meet all conditions at once.

In the example, the request returns the item named “Andy Mahn”: the value Andy* means that the name must start with Andy.

The use_wildcard=true parameter enables pattern matching for all conditions: * stands for any number of characters, ? for a single character. By default, use_wildcard=false, which means exact matching.

There are two limitations: you can't filter by workflow columns, and you can't combine filters with include_deleted=true.

GET https://api.pyrus.com/v4/catalogs/6625
?column=Name
&value=Andy%2A
&use_wildcard=true

Response body

{
  "catalog_id": 6625,
  "name": "Clients",
  "catalog_headers": [
    {
      "name": "Name",
      "type": "text"
    },
    {
      "name": "Company",
      "type": "text"
    }
  ],
  "items": [
    {
      "item_id": 15202,
      "values": [
        "Andy Mahn",
        "123 Warehousing"
      ]
    }
  ]
}

curl

curl -X GET \
  'https://api.pyrus.com/v4/catalogs/6625?column=Name&value=Andy%2A&use_wildcard=true' \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json'

Parameters

include_deletedIncludes deleted catalog items in the query results. Available only for users with organization administrator rights. Can't be used together with filters.
columnThe name of the column to filter by. Can be passed several times.
valueThe value for the corresponding column. The number of value parameters must match the number of column parameters. To find empty values, pass an empty string (not null).
use_wildcardOptional (true or false). Enables pattern matching for all conditions: * stands for any number of characters, ? for a single character. The default is false, which means exact matching.

For several conditions, repeat the column and value pairs, for example: ?column=Name&value=Andy%20Mahn&column=Company&value=123%20Warehousing. All conditions apply at once.

GET /catalogs

This method returns all catalogs without their elements.

GET https://api.pyrus.com/v4/catalogs

Response body

{
    "catalogs": [
        {
            "catalog_id": 31816,
            "name": "Catalog1",
            "version": 151199,
            "deleted": false,
            "supervisors": [
                1731
            ],
            "external_version": 0
        },
        {
            "catalog_id": 31817,
            "name": "Catalog2",
            "version": 109104,
            "deleted": false,
            "external_version": 0
        }
]
}

curl

curl -X GET \
  https://api.pyrus.com/v4/catalogs \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json'

PUT /catalogs

Create a catalog. This method returns a catalog with all its elements.

PUT https://api.pyrus.com/v4/catalogs

Request body

{
  "name": "Clients",
  "catalog_headers": [
    "Name",
    "Company"
  ],
  "items": [
    {
      "values": [
        "Reatha Middendorf",
        "Acme, inc."
      ]
    },
    {
      "values": [
        "Daedra Ullrich",
        "Widget Corp"
      ]
    },
    {
      "values": [
        "Andy Mahn",
        "123 Warehousing"
      ]
    }
  ]
}

Response body

{
  "catalog_id": 6625,
  "name": "Clients",
  "catalog_headers": [
    {
      "name": "Name",
      "type": "text"
    },
    {
      "name": "Company",
      "type": "text"
    }
  ],
  "items": [
    {
      "item_id": 15200,
      "values": [
        "Reatha Middendorf",
        "Acme, inc."
      ]
    },
    {
      "item_id": 15201,
      "values": [
        "Daedra Ullrich",
        "Widget Corp"
      ]
    },
    {
      "item_id": 15202,
      "values": [
        "Andy Mahn",
        "123 Warehousing"
      ]
    }
  ]
}

curl

curl -X PUT \
  https://api.pyrus.com/v4/catalogs/ \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Clients",
  "catalog_headers": [
    "Name",
    "Company"
  ],
  "items": [
    {
      "values": [
        "Reatha Middendorf",
        "Acme, inc."
      ]
    },
    {
      "values": [
        "Daedra Ullrich",
        "Widget Corp"
      ]
    },
    {
      "values": [
        "Andy Mahn",
        "123 Warehousing"
      ]
    }
  ]
}'

POST /catalogs/{catalog-id}

Sync a catalog. This method updates catalog headers and items. You must define all the values and text columns that need to remain in the catalog. All unspecified items and text columns will be deleted. This method only changes the values. To do this, you must pass it explicitly in the list of columns. You cannot add or delete workflow columns using this method. The first column of the catalog is the key parameter. Therefore, its name cannot be changed. This method returns a list of items that have been added, modified, or deleted.

POST https://api.pyrus.com/v4/catalogs/6625

Request body

{
  "apply": true,
  "catalog_headers": [
    "Name",
    "Company"
  ],
  "items": [
    {
      "values": [
        "Reatha Middendorf",
        "Acme"
      ]
    },
    {
      "values": [
        "Daedra Ullrich",
        "Widget Corp"
      ]
    },
    {
      "values": [
        "Jean Overturf",
        "Demo Company"
      ]
    }
  ]
}

Response body

{
  "apply": true,
  "added": [
    {
      "item_id": 15205,
      "values": [
        "Jean Overturf",
        "Demo Company"
      ]
    }
  ],
  "deleted": [
    {
      "item_id": 15202,
      "values": [
        "Andy Mahn",
        "123 Warehousing"
      ]
    }
  ],
  "updated": [
    {
      "item_id": 15200,
      "values": [
        "Reatha Middendorf",
        "Acme"
      ]
    }
  ],
  "catalog_headers": [
    {
      "name": "Name",
      "type": "text"
    },
    {
      "name": "Customer Company",
      "type": "text"
    }
  ]
}

curl

curl -X POST \
  https://api.pyrus.com/v4/catalogs/6625 \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "apply": true,
  "catalog_headers": [
    "Name",
    "Company"
  ],
  "items": [
    {
      "values": [
        "Reatha Middendorf",
        "Acme"
      ]
    },
    {
      "values": [
        "Daedra Ullrich",
        "Widget Corp"
      ]
    },
    {
      "values": [
        "Jean Overturf",
        "Demo Company"
      ]
    }
  ]
}'

Parameters

applyDefine this as true if you want to apply changes, or false if you want to calculate which items will be added/deleted/updated.
catalog_headersAn array of catalog headers. All unspecified text columns will be deleted.
itemsAn array of catalog items. All unspecified items will be deleted.

POST /catalogs/{catalog-id}/diff

Change catalog items. This method allows you to insert new catalog items, modify or delete existing ones. The first column of the catalog is the key parameter. To insert or modify a row (also called upsert) please pass an array of values for each item. To delete items you need only an array of keys. This method returns a list of items that have been added, modified, or deleted (it’s the same as a sync catalog method does).

POST https://api.pyrus.com/v4/catalogs/6625/diff

Request body

{
    "upsert": [
    {
        "values": [
            "Reatha Middendorf",
            "Acme"
        ]
    },
    {
        "values": [
            "Daedra Ullrich",
            "Widget Corp"
        ]
    }],
    "delete": ["Jean Overturf"]
}

Response body

{
    "apply": true,
    "added": [
    {
        "item_id": 24807,
        "values": [
            "Daedra Ullrich",
            "Widget Corp"
        ]
    }],
    "deleted": [
    {
        "item_id": 23169,
        "values": [
            "Jean Overturf",
            "Demo Company"
        ]
    }],
    "updated": [
    {
        "item_id": 23178,
        "values": [
            "Reatha Middendorf",
            "Acme"
        ]
    }],
    "catalog_headers": [
    {
        "name": "Name",
        "type": "text"
    },
    {
        "name": "Company name",
        "type": "text"
    }]
}

curl

curl -X POST \
 https://api.pyrus.com/v4/catalogs/6625/diff \
 -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
 -H 'Content-Type: application/json' \
 -d '{
 "upsert": [
 {
   "values": [
     "Reatha Middendorf",
     "Acme"
   ]
 },
 {
   "values": [
     "Daedra Ullrich",
     "Widget Corp"
   ]
 }],
 "delete": ["Jean Overturf"]
}'

Parameters

upsertAn array of catalog items to be inserted or modified.
deleteAn array of item keys (values of the first column) to be deleted.

Was this article helpful?