Pazy Documentation

Authentication

All requests require an API key in the request headers. Headers:

Authorization: Api-Key YOUR_API_KEY
Content-Type: application/json

Request

Content-Type: application/json

Path Parameters

Parameter	Type	Required	Description
`vendorId`	string	Yes	Unique identifier of the vendor to update

Body Parameters

The request body has a single top-level key, vendorData. All fields inside vendorData are optional — only the fields you include will be considered for update. Fields you omit are left untouched.

Parameter	Type	Required	Description
`vendorData`	object	Yes	Container for the partial update payload
`vendorData.name`	string	No	Vendor display name (1–255 characters)
`vendorData.email`	string	No	Vendor email address (must be a valid email format)
`vendorData.phone`	string	No	Vendor phone number — must include country code in `+{country_code}{number}` format (e.g., `+919876543210`)
`vendorData.owner`	string	No	New owner — pass a user id / slug of a user in your organization
`vendorData.address`	object	No	Vendor address. Existing address fields are merged with the values you send. See Address Fields below.
`vendorData.communications`	object	No	Payment confirmation email recipients. See Communications Fields below.
`vendorData.customFields`	object	No	Map of flex-field slug → `{ type, value }`. See Custom Fields below.

Address Fields

vendorData.address accepts the following properties (all optional, merged with existing values):

Field	Type	Description
`addressLine1`	string	Address line 1
`addressLine2`	string	Address line 2
`city`	string	City
`state`	string	State
`zipCode`	string	Postal / ZIP code
`pinCode`	string	Postal / PIN code (alias preferred by the persistence layer)
`country`	string	Country
`locality`	string	`DOMESTIC` or `INTERNATIONAL`

Communications Fields

vendorData.communications configures who receives payment confirmation emails. Each list contains user ids / slugs from your organization.

Field	Type	Description
`to`	array of strings	”To” recipients (user ids)
`cc`	array of strings	”CC” recipients (user ids)
`bcc`	array of strings	”BCC” recipients (user ids)

Custom Fields

vendorData.customFields is a map keyed by the flex-field slug configured for your organization. Each value is an object with type and value:

Field	Type	Description
`type`	string	Flex-field type. Must match the field definition. One of `VARCHAR`, `DATETIME`, `DROPDOWN`, `NUMERIC`
`value`	string \| number	`VARCHAR`: text; `DATETIME`: date in `YYYY-MM-DD`; `DROPDOWN`: tag value id; `NUMERIC`: a number

Code Examples

curl -X PATCH https://api.pazy.io/v1.0/vendor/<vendorId> \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendorData": {
      "name": "Acme Suppliers",
      "email": "vendor@example.com",
      "phone": "+919876543210"
    }
  }'

Success Response

HTTP Status: 200 OK The endpoint always returns 200 OK when the request itself is valid — even when individual fields fail to update. Inspect context.updates.<field> to see the per-field outcome. Response Fields:

Field	Type	Description
`ok`	boolean	Indicates whether the request was processed
`update`	boolean	Indicates that the update operation ran
`error`	object \| null	Top-level error if the entire request failed (`null` when per-field results are returned)
`context`	object	Container for per-field results
`context.updates`	object	Map keyed by the field name you sent in `vendorData`
`context.updates.<field>.update`	boolean	`true` if that field was updated; `false` if it was rejected or skipped
`context.updates.<field>.error`	object	Present only when `update` is `false`. Contains a `code` and `message` describing the reason.

Some fields attach extra metadata when they fail:

Field	Failure code	Extra fields returned
`name`	`DUPLICATE_VENDOR_NAME`	`isDuplicate: true`, `duplicateVendor: { id, name }`
`communications`	`INVALID_USER_IN_COMMUNICATIONS`	`wrongUserSlugs: [...]`

Response Example — Successful Multi-Field Update

{
  "ok": true,
  "update": true,
  "error": null,
  "context": {
    "updates": {
      "name": { "update": true },
      "email": { "update": true },
      "phone": { "update": true }
    }
  }
}

Response Example — Mixed Success and Failures

{
  "ok": true,
  "update": true,
  "error": null,
  "context": {
    "updates": {
      "name": {
        "update": false,
        "error": {
          "code": "DUPLICATE_VENDOR_NAME",
          "message": "Vendor with the same name already exist"
        },
        "isDuplicate": true,
        "duplicateVendor": {
          "id": "<otherVendorId>",
          "name": "Acme Trading"
        }
      },
      "phone": {
        "update": false,
        "error": {
          "code": "SAME_VALUE_GIVEN",
          "message": "Phone is same as the current one"
        }
      },
      "owner": { "update": true }
    }
  }
}

Response Example — `communications` with Unknown Users

{
  "ok": true,
  "update": true,
  "error": null,
  "context": {
    "updates": {
      "communications": {
        "update": false,
        "error": {
          "code": "INVALID_USER_IN_COMMUNICATIONS",
          "message": "ERROR_CODE INVALID_USER_IN_COMMUNICATIONS not found"
        },
        "wrongUserSlugs": ["<unknownUserId>"]
      }
    }
  }
}

Response Example — `customFields` Mixed Outcome

{
  "ok": true,
  "update": true,
  "error": null,
  "context": {
    "updates": {
      "customFields": {
        "fasttrack": { "update": true },
        "test-upload": { "update": true },
        "wrong-tag": {
          "update": false,
          "error": {
            "code": "INVALID_TAG",
            "message": "Invalid tag key"
          }
        },
        "hinge": {
          "update": false,
          "error": {
            "code": "INVALID_TAG_TYPE",
            "message": "Tag type is of 'DATETIME' but received VARCHAR"
          }
        }
      }
    }
  }
}

Per-Field Error Codes

Field	Error code	When it occurs
`name`	`DUPLICATE_VENDOR_NAME`	Another vendor in the same organization already uses this name. Response includes `duplicateVendor.id` and `duplicateVendor.name`.
`name`, `email`, `phone`, `owner`, `address`, `communications`	`SAME_VALUE_GIVEN`	The submitted value matches the existing value — nothing changed
`phone`	`INVALID_NUMBER`	Phone number does not follow `+{country_code}{number}`
`owner`	`INVALID_OWNER`	Owner user id does not exist in your organization
`communications`	`INVALID_USER_IN_COMMUNICATIONS`	One or more of the `to` / `cc` / `bcc` slugs is not a valid user. Invalid ids are returned in `wrongUserSlugs`.
`customFields.<slug>`	`INVALID_TAG`	The slug does not match any flex field configured for the organization
`customFields.<slug>`	`INVALID_VALUE_ID`	For `DROPDOWN`: the value id is unknown or not linked to that tag
`customFields.<slug>`	`INVALID_TAG_TYPE`	The `type` sent does not match the configured flex-field type
`customFields.<slug>`	`INVALID_DATE_INPUT`	For `DATETIME`: value is not in `YYYY-MM-DD`

Error Responses

Validation Error

HTTP Status: 400 Bad Request

{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed: /vendorData/email: must match format \"email\""
  }
}

Vendor Not Found

HTTP Status: 404 Not Found

{
  "ok": false,
  "error": {
    "code": "VENDOR_NOT_FOUND",
    "message": "Vendor not found"
  }
}

Access Denied

HTTP Status: 403 Forbidden

{
  "ok": false,
  "error": {
    "code": "ACCESS_DENIED",
    "message": "Access denied: You can only view vendors you own"
  }
}

Returned when the caller is neither an admin / bookkeeper nor the vendor’s owner.

Authentication Errors

HTTP Status: 401 Unauthorized

{
  "ok": false,
  "error": {
    "code": "MISSING_CREDENTIALS",
    "message": "Missing Credentials"
  }
}

{
  "ok": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API Key"
  }
}

Permission Errors

HTTP Status: 403 Forbidden

{
  "ok": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "Permission check failed - PERMISSION_CHECK_FAILED"
  }
}

Internal Error

HTTP Status: 500 Internal Server Error

{
  "ok": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal error"
  }
}

Best Practices

Send only the fields you want to change — omitted fields are left untouched
Always inspect context.updates.<field> for the outcome; a 200 OK does not guarantee every field was applied
For phone, normalize to E.164 (+{country_code}{number}) before sending — values without + are rejected with INVALID_NUMBER
For address, the API merges with the existing record. Send only the keys you want to change rather than the full address
For customFields, the type you send must exactly match the field’s configured type — a mismatch is rejected per-field with INVALID_TAG_TYPE
Use the Vendor Details API to fetch the current state, and the Vendor Audit Trail API to inspect change history after updates

Documentation Index

​Authentication

​Request

​Path Parameters

​Body Parameters

​Address Fields

​Communications Fields

​Custom Fields

​Code Examples

​Success Response

​Response Example — Successful Multi-Field Update

​Response Example — Mixed Success and Failures

​Response Example — communications with Unknown Users

​Response Example — customFields Mixed Outcome

​Per-Field Error Codes

​Error Responses

​Validation Error

​Vendor Not Found

​Access Denied

​Authentication Errors

​Permission Errors

​Internal Error

​Best Practices